Installation & upgrades

NovuHub is a single Python service (Flask behind gunicorn) with PostgreSQL, optional Redis, and file storage on local disk or any S3-compatible bucket. Everything is configured through environment variables, so a server or domain move never means editing code.

Requirements

• Linux host, Python 3.11+, Node.js 18+ (only for the front-end build step)
• PostgreSQL 14+ (SQLite works for evaluation)
• nginx (or any TLS-terminating reverse proxy)
• Optional: Redis 6+ (shared rate limits and real-time fan-out across workers)
• Optional: an S3-compatible bucket (Hetzner Object Storage, R2, S3, B2, MinIO)
• Outbound SMTP or a transactional email provider for invitations and resets

First installation (systemd)

sudo mkdir -p /var/www/novuhub && sudo chown $USER /var/www/novuhub
git clone <your-repo-url> /var/www/novuhub && cd /var/www/novuhub
python3 -m venv venv && venv/bin/pip install -r requirements.txt
cp .env.example .env            # then edit: SECRET_KEY, APP_BASE_URL, DATABASE_URL, SMTP_*
bash build_frontend.sh          # bundles, minifies and pre-compresses the front-end
sudo cp deploy/novuhub.service deploy/novuhub-worker.service /etc/systemd/system/
sudo cp deploy/nginx-novuhub.conf /etc/nginx/sites-available/novuhub
sudo ln -s /etc/nginx/sites-available/novuhub /etc/nginx/sites-enabled/
sudo systemctl daemon-reload && sudo systemctl enable --now novuhub novuhub-worker
sudo nginx -t && sudo systemctl reload nginx

Tables are created on first start; new columns added by later releases are applied automatically at boot (ensure_columns), so upgrades never need a manual migration.

The worker service runs the automation engine (workflow rules, reminders, webhook and email queues, weekly recap) every NOVUHUB_ENGINE_MINUTES (default 10). Keep NOVUHUB_ENGINE_IN_WEB=0 in the web service so the engine runs only in the worker. The optional novuhub-mailscan.timer scans the finance mailbox every 10 minutes.

Docker

docker compose up -d starts the app, PostgreSQL and Redis from the bundled docker-compose.yml; the same .env file applies.

Configuration reference

The full annotated list is in .env.example.

Upgrading

cd /var/www/novuhub
git pull
venv/bin/pip install -r requirements.txt
bash build_frontend.sh
sudo systemctl restart novuhub novuhub-worker

Read the changelog entry for the release first: it lists any new environment switch. Schema additions apply themselves on start-up. Roll back with git checkout <previous-tag> and the same four commands.

Backups and restore

• ops/backup.sh dumps the database and local uploads; set OFFSITE_S3 or RCLONE_REMOTE in .env so dumps leave the machine. Schedule it nightly.
• ops/restore_verify.sh restores the newest dump into a scratch database and checks it — schedule weekly and alert on a non-zero exit.
• ops/restore.sh <dump.sql.gz> restores onto a server; ops/MIGRATION.md covers moving to a new host or domain (keep SECRET_KEY, re-point DATABASE_URL and the bucket).

Health and monitoring

Point your uptime monitor at /readyz. Logs go to journald (journalctl -u novuhub -u novuhub-worker); every request carries an X-Request-ID that appears in error logs and, when configured, in Sentry.

Scaling

• More gunicorn workers (--workers) or more hosts behind the proxy: set REDIS_URL so rate limits, login throttling and live updates are shared.
• Move PostgreSQL to a managed service with point-in-time recovery: only DATABASE_URL changes.
• Object storage keeps uploads off the app host and makes the app stateless.
• The front-end ships as a core bundle (≈160 KB gzip) plus twelve lazily loaded chunks (finance, HR, portfolios, CRM, messages, calendar, people, mind map, docs, learning, settings, analysis), pre-compressed and served with immutable cache headers; a CDN in front of /static/ is optional.

See ops/RUNBOOK.md for the operational checklist.