Totem Server

Guided introspection groups at totem.org

Basic Commands

• make install_local - Install Python (via uv) and JS dependencies for local tooling (linting, type checking, etc.)
• make - Start the dev environment (Docker, asset watching, livereload)
• make assets - Build frontend assets (Tailwind CSS, JS bundles)
• make test - Run Python and JS test suites
• make deploy - Deploy to staging server

Setting Up

Requirements:

• Docker Compose
• uv
• Bun

For macOS

brew install bun uv

Steps:

• Run make install_local to install dependencies.
• Run make to bring up the dev environment. You may need to create a blank .env file in the root directory.
• Run make assets to compile the assets.

Running Tests

• Run make test to run the tests.

Deployment

• make deploy to deploy to the staging server.
• make deploy-prod to deploy to the production server.

Deployment notes

• Totem used dokku for deployment. The Dockerfile is used to build the image.
  • Configure dokku to use the production Dockerfile: dokku builder:set totem selected dockerfile and dokku builder-dockerfile:set totem dockerfile-path compose/production/django/Dockerfile.

Update PostgreSQL config

The production Postgres config is at compose/production/postgres/postgresql.conf. To apply changes:

• Find the Dokku config directory: dokku postgres:info totemdb --config-dir
• Copy the config: scp compose/production/postgres/postgresql.conf <vps>:<config-dir>/postgresql.conf
• Restart Postgres: dokku postgres:restart totemdb

Note: shared_buffers changes require a full restart to take effect.

After a Postgres point update, refresh collation versions to suppress warnings:

docker exec -i dokku.postgres.totemdb psql -U postgres <<'EOF'
SELECT format('ALTER DATABASE %I REFRESH COLLATION VERSION', datname)
FROM pg_database WHERE datallowconn \gexec
EOF

For the local dev database:

docker exec -i totem_local_postgres psql -U debug -d totem <<'EOF'
SELECT format('ALTER DATABASE %I REFRESH COLLATION VERSION', datname)
FROM pg_database WHERE datallowconn \gexec
EOF

Restore DB from backup

• Download backup locally
• Take app offline: dokku ps:stop totem
• scp backup into VM home folder
• tar -xf backup.tgz
• docker cp backup/export dokku.postgres.totemdb:/tmp/export
• docker exec -i dokku.postgres.totemdb bash

To do a full wipe and restore:

• dropdb -U postgres totemdb
• createdb -U postgres -T template0 totemdb
• pg_restore -U postgres -d totemdb < /tmp/export
• Then redeploy or dokku ps:start totem