APBoard v3 · Documentation
Documentation

Everything you need to install, configure and run APBoard. Explained in full, even for complete beginners.

APBoard › Documentation › Troubleshooting

Troubleshooting

This page lists common APBoard installation and operation problems. Start with the symptom you see, then check the commands and explanations below it.

Docker container does not start

First check the status and logs from the deploy/ directory.

bash 
cd /home/apboard/forum/deploy
docker compose ps
docker compose logs --tail 200 app
docker compose logs --tail 200 db

If the database is unhealthy, check the passwords in .env and whether deploy/db/ already contains an old database initialized with different credentials. If the app is unhealthy, check whether APBOARD_URL, APBOARD_DB_HOST and the database password are correct.

Traefik shows 404 or no certificate

A Traefik 404 usually means that the router rule does not match your domain or that the container is not connected to the proxy network.

bash 
docker network inspect proxy
docker compose config | grep APBOARD_DOMAIN
docker compose ps

For certificates, make sure the domain already points to the server and ports 80 and 443 are reachable from the internet.

The setup wizard does not appear

The setup wizard only appears when config.php does not exist. If config.php exists, APBoard treats the installation as complete and redirects /setup/ to the forum.

In Docker this is expected. Docker creates config.php before Apache starts, so Docker installations do not use the browser setup wizard.

Database connection failed

Check the database host first. In Docker it must be db. On a plain server it is often localhost or 127.0.0.1.

bash 
# Docker
cd /home/apboard/forum/deploy
docker compose exec db mariadb -u apboard -p apboard

# Plain server
mysql -u apboard -p apboard

If login fails, the database user, password or database name is wrong. If login works but APBoard fails, compare those values with .env or config.php.

CSS, JavaScript or icons are missing

APBoard serves frontend libraries through symlinks in public/assets/. Docker creates them on every container start. The plain setup wizard creates them after installation.

bash 
ls -la public/assets
ls -la public/assets/js
ls -la public/assets/font-awesome

On Apache, Options FollowSymLinks must be enabled for the public/ directory. On nginx, symlinks must point to readable paths.

URLs return 404 except the homepage

The web server rewrite rules are missing or incomplete. APBoard needs a fallback to index.php and explicit rules for ActivityPub and well known endpoints. Compare your Apache or nginx configuration with the examples in the plain installation guide.

Uploads fail

The web server must be allowed to write into public/shared/uploads/. PHP upload limits must also be large enough for the files you allow in the admin settings.

bash 
ls -ld public/shared public/shared/uploads
php -i | grep -E 'upload_max_filesize|post_max_size|memory_limit'

Email does not arrive

Check host, port, security mode, username, password, sender address and sender name. Use starttls with port 587 and smtps with port 465 unless your mail provider says otherwise.

Also check the spam folder. If mail arrives in spam, set SPF, DKIM and DMARC for your sender domain or use a trusted mail provider.

Admin password is lost

Use the normal password reset flow if mail works. If mail does not work, create a PHP password hash and update the admin row in the database.

bash 
php -r "echo password_hash('NewStrongPassword', PASSWORD_DEFAULT);"
sql 
UPDATE apb_user SET password = 'PASTE_HASH_HERE' WHERE id = 1;

Ask for help

If you ask for help in the APBoard forum or on Forgejo, include the installation type, APBoard version, PHP version, database version, web server type and exact error messages. For Docker, also include docker compose ps and the last app logs with passwords removed.

Back Update APBoard