====== WriteFreely Database Issues ======

WriteFreely fails to start or uses SQLite instead of MySQL.

===== Symptom =====

WriteFreely container restarts repeatedly. Logs show "Connecting to sqlite3 database" instead of MySQL. Migration errors about missing tables. Admin user creation fails.

===== Cause =====

WriteFreely is not configured to use MariaDB. It defaults to SQLite if no database connection is properly configured.

===== Fix =====

Add MariaDB container and configure WriteFreely to use MySQL.

**Steps:**

  1. Add MariaDB container to docker-compose.yml:
```yaml
folkzone-write-db:
  image: mariadb:10.11
  container_name: folkzone_write_db
  restart: unless-stopped
  networks: [folkzone_net]
  environment:
    MARIADB_DATABASE: writefreely
    MARIADB_USER: writefreely
    MARIADB_PASSWORD: ${WRITE_MYSQL_PASSWORD}
    MARIADB_ROOT_PASSWORD: ${WRITE_MYSQL_ROOT_PASSWORD}
  volumes:
    - folkzone_write_db:/var/lib/mysql
  healthcheck:
    test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
    interval: 10s
    timeout: 5s
    retries: 5
```

  2. Update WriteFreely service with database connection:
```yaml
folkzone-write:
  image: algernon/writefreely:latest
  container_name: folkzone_write
  restart: unless-stopped
  networks: [folkzone_net]
  environment:
    WRITEFREELY_BIND_HOST: 0.0.0.0
    WRITEFREELY_BIND_PORT: "8080"
    WRITEFREELY_SITE_NAME: folk.write
    WRITEFREELY_HOST: https://write.folk.zone
    WRITEFREELY_DB_HOST: folkzone-write-db
    WRITEFREELY_DB_USER: writefreely
    WRITEFREELY_DB_PASSWORD: ${WRITE_MYSQL_PASSWORD}
    WRITEFREELY_DB_NAME: writefreely
    WRITEFREELY_DB_TYPE: mysql
  volumes:
    - folkzone_write_data:/data
  depends_on:
    folkzone-write-db:
      condition: service_healthy
```

  3. Update config.ini to use MySQL:
```bash
docker run --rm -v folkzone_write_data:/data alpine sh -c 'cat > /data/config.ini << EOF
[database]
type     = mysql
username = writefreely
password = <your-password>
database = writefreely
host     = folkzone-write-db
port     = 3306
EOF
'
```

  4. Clear old SQLite data:
```bash
docker run --rm -v folkzone_write_data:/data alpine sh -c 'rm -f /data/writefreely.db /data/keys/*.aes256'
docker run --rm -v folkzone_write_data:/data alpine sh -c 'touch /data/writefreely.db'
```

  5. Reset MySQL database:
```bash
docker exec folkzone_write_db mysql -u root -p<root-password> -e 'DROP DATABASE IF EXISTS writefreely; CREATE DATABASE writefreely;'
```

  6. Restart services:
```bash
docker compose up -d folkzone-write-db folkzone-write
```

  7. Create admin user:
```bash
docker exec -w /data folkzone_write /writefreely/writefreely --create-admin <username>:<password>
```

===== Prevention =====

Configure database connection during initial WriteFreely setup. The username "admin" is reserved in WriteFreely, use a different username like "folkadmin".

===== See Also =====

  * [[folkzone:troubleshooting:start|Troubleshooting Index]]
  * [[folkzone:services:write|WriteFreely Service]]

Last updated: 2026-06-19
  * [[folkzone:start|Return to folkzone]]