Self-hosting and deployment

Supported topology: one API replica. Use SQLite on local persistent storage or PostgreSQL. SQLite on NFS and multi-replica operation—even with PostgreSQL—are not supported.

Architecture

Browser -> 127.0.0.1:8888 -> Nginx -> Astro
                                  -> AdonisJS -> SQLite /data or PostgreSQL

Install

1. Generate private configuration:

npm run init:env

2. Validate and start:

docker compose config --quiet
docker compose up -d --build --wait
docker compose ps

3. Open http://localhost:8888; use private .env SETUP_TOKEN to create first administrator. No default accounts; public registration stays off unless REGISTRATION_ENABLED=true.

docker compose pull api web
docker compose up -d --no-build --wait

Configuration

.env.example lists every Compose setting. Keep .env private and back it up encrypted.

After environment changes, recreate affected services:

docker compose up -d --force-recreate api web proxy

docker compose restart does not load changed environment values.

Automation Credential Keys And Network

{"active":"key-1","keys":{"key-1":"<32-byte-base64-key>"}}

Every value encodes exactly 32 random bytes. New initialization supplies it. On older installs, privately generate/add the complete one-line keyring and recreate API before credential/OAuth use. Never put it in web/UI/logs/Git. Missing keyring leaves tasks available but credential work explicitly unavailable.

Keep every key referenced by retained encrypted rows. Changing active key does not re-encrypt old versions. Losing the final key copy is unrecoverable from the encrypted database.

Exceptions are high-trust: prefer network allowlists, never broad/user-controlled origins.

PostgreSQL

Initializer creates a private PostgreSQL password/URL but leaves SQLite selected. For a new bundled PostgreSQL deployment before first start:

COMPOSE_PROFILES=postgres
DB_CONNECTION=pg

• Bundled URL points to postgres service.
• External PostgreSQL: leave profile empty; set DATABASE_URL to external server.
• Changing engines is data migration, not a variable switch that copies existing data.

Live Table Databases

Live sources are separate from Hopya’s own DB_CONNECTION. Enable only used destinations/files:

SQL_ALLOWED_HOSTS=postgres.internal:5432,mysql.internal:3306
SQL_SQLITE_ROOT=/data/external-tables

Recreate API, then Import & export → Live SQL databases to connect. AES-256-GCM uses stable SQL_CONNECTION_KEY or APP_KEY; back it up with database. Changing key does not re-encrypt connections.

Back up source databases separately. Workspace export omits credentials/remote rows; per-Table CSV/JSON can export rows. Audit intent precedes remote write, but two-database commits are not atomic: reload/reconcile an interrupted write, never automatically replay it.

Customize The Landing Page

This is the application’s optional landing, separate from this documentation/marketing site.

docker compose up -d --build web

HTTPS

1. Put a trusted HTTPS reverse proxy before loopback Hopya.
2. Set exact external APP_URL, e.g. https://tasks.example.com.
3. Forward entire site including /api and /health, preserving Host/Origin.
4. Configure inner real-IP trust for only the exact outer proxy address; inner Nginx replaces forwarded client-address headers before Adonis.

Never publish 3333/4321 or disable Origin checks. Secure cookies and mutation checks need accurate origin. Never trust all sources or broad/shared subnet forwarding.

Attachments

Password Recovery

OIDC And AI

Backup And Restore

Workspace export is not a full backup. Retain original private .env and every key needed by old credentials.

Cold SQLite backup

mkdir -p backups
chmod 700 backups
umask 077
docker compose stop proxy api
tar -czf backups/hopya-data.tgz -C data .
tar -tzf backups/hopya-data.tgz
sha256sum backups/hopya-data.tgz
docker compose up -d --wait

Store archive/encrypted configuration off-host. Verify full keyring presence without printing it.

For PostgreSQL, stop API writes and use supported pg_dump/pg_restore, not a data-volume archive. Verify dump before restart; coordinate filesystem/S3 object backup.

Restore without overwriting old data

docker compose stop proxy api
mkdir -p restore-data
chmod 700 restore-data
tar --no-same-owner -xzf backups/hopya-data.tgz -C restore-data

Create ignored compose.restore.yaml:

services:
  api:
    volumes:
      - ./restore-data:/data

Validate/start with both files:

docker compose -f docker-compose.yml -f compose.restore.yaml config --quiet
docker compose -f docker-compose.yml -f compose.restore.yaml up -d --wait

Verify login, workspace counts, writes, permissions, private downloads before retiring old volume. Old backups can revive credentials: revoke affected access again before reopening.

Upgrades

1. Read release notes; take verified cold backup.
2. Retain .env, especially application/keyring secrets. Older installs add keyring privately, never rerun initializer over existing setup.
3. Update checkout; docker compose build --pull.
4. docker compose up -d --wait.
5. Verify health/login/writes/attachments and configured credential decryption against a non-destructive destination.

Troubleshooting

docker compose ps
docker compose logs --tail=100 api web proxy

Developers may use npm run test:deployment for an isolated Docker check with unique temporary resources, not operator .env. This documentation cleanup does not run that integration test.