Troubleshooting¶

This page lists common issues and quick diagnostics for SmallBlock CMS.

Dev Server Will Not Start¶

Run: smallblock check for environment validation (DB URL, secrets).
Ensure dependencies are installed: python3 -c "import pkgutil; print('ok')"
Check logs: run the command with --verbose or inspect the console output.

502 Bad Gateway (Nginx)¶

App process down? systemctl status smallblock
Socket label/permissions: - Socket exists? ls -l /srv/smallblock/run/smallblock.sock - SELinux label: ls -Z /srv/smallblock/run/smallblock.sock - Reapply labels:
sudo semanage fcontext -a -t httpd_var_run_t "/srv/smallblock/run(/.*)?" sudo restorecon -R /srv/smallblock/run
Nginx to app connectivity: check /var/log/nginx/error.log

Database Connection Refused¶

Is the service running? PostgreSQL: systemctl status postgresql MariaDB: systemctl status mariadb
Credentials/host/port in DATABASE_URL correct?
For PostgreSQL local socket auth, ensure the role exists and pg_hba.conf permits local connections.

Migrations Fail¶

Re-run with verbosity: smallblock migrate --verbose
Check privileges (create/alter) for the DB user.
If a partial migration occurred, roll back the last migration and re-apply.

Permission Denied on Static/Media¶

Paths exist and owned by the app user:

sudo mkdir -p /srv/smallblock/{static,media}
sudo chown -R smallblock:smallblock /srv/smallblock/{static,media}

SELinux types for files served by Nginx:

sudo semanage fcontext -a -t httpd_sys_content_t "/srv/smallblock/static(/.*)?"
sudo semanage fcontext -a -t httpd_sys_content_t "/srv/smallblock/media(/.*)?"
sudo restorecon -R /srv/smallblock/{static,media}

Firewall / Port Access¶

Open HTTP/HTTPS only:

sudo firewall-cmd --add-service=http --permanent
sudo firewall-cmd --add-service=https --permanent
sudo firewall-cmd --reload

Keep DB ports closed to the Internet; prefer localhost.

Collecting Diagnostics¶

App logs: journalctl -u smallblock -e
Nginx: /var/log/nginx/access.log and /var/log/nginx/error.log
System events: journalctl -xe