Admin guide
This guide is for the person who installs and runs an AlianHub instance: the server, its database, its files, its mail and its upgrades. If you only use AlianHub, start with the User guide instead.
AlianHub is one Node.js process (the API, the real-time Socket.io server and the built web app) and one MongoDB server. Uploaded files live on the server's disk or in an S3-compatible bucket. Everything else (mail, sign-in providers, AI) is optional and can be set up after the first login.
What an admin does
| Job | Where |
|---|---|
| Install the server and the database | Install with Docker or Install on a server |
| Create the owner account and first workspace | First run |
| Put it behind HTTPS | HTTPS and reverse proxy |
| Set mail, storage, sign-in, AI and security options | The Instance console, Environment variables |
| Take and test backups | Backup and restore |
| Upgrade to new releases | Upgrades |
| Watch health and logs, fix problems | Logs and monitoring, Troubleshooting |
Inviting people, roles and workspace settings are done by a workspace owner or admin from Settings › Members and the other workspace settings; see People and roles.
Two ways to install
| Docker (recommended) | On a server (Node 20 + MongoDB) | |
|---|---|---|
| What you install | Docker with Compose | Node.js 20, MongoDB 6 or 7, a process manager |
| Commands to a running app | three | npm run setup, then npm start under pm2 or systemd |
| Database | MongoDB 7 in a container, on a private network | your own MongoDB, local or hosted |
| Upgrades | docker compose pull && docker compose up -d | git pull, install, rebuild the web app, restart |
| Good for | most installs | hosts without Docker, shared hosting with cPanel, development |
Both run the same code and read the same environment variables.
The Instance console
The account that ran setup is the instance owner. Only that account sees Settings › Instance, the console for the whole server:
- Health: database, storage, mail, migrations, automation queue, backups and scheduled jobs, plus a readiness card listing what is still missing for production.
- Settings: General, Mail, Storage, AI, Sign-in, Calling and Security, each with a Test button where there is something to test.
- Backups, Upgrade and Logs.
- Enforcement, Egress, Instruction guard, Knowledge, AI providers and Stats for the security and AI controls.
A value set in the environment always wins over the console and shows as locked. See The Instance console.
Production checklist
Work through this before you invite your team. The readiness card on Settings › Instance › Health tracks the first five.
- HTTPS. A reverse proxy with a certificate in front of port 4000,
WEBURLandAPIURLset to thehttps://address,TRUST_PROXYset, WebSocket upgrades forwarded. See HTTPS and reverse proxy. - Mail. Amazon SES, Resend or SMTP, tested with the Test button. Without it, invitations and password resets cannot be sent. See Mail.
- Storage. Decide between the server's disk and an S3-compatible bucket before people upload much; switching later means copying files. See File storage.
- Backups. Take one from Settings › Instance › Backups, copy it off the host, and restore it once on a throwaway copy. Schedule them with
INSTANCE_ADMIN_KEYand cron. See Backup and restore. - Migrations up to date. They run on their own at boot; the Upgrade page shows any that failed. See Upgrades.
- Secrets. A long random
JWT_SECRET(openssl rand -hex 32) that you keep stable,.envreadable only by the service user, no real values in version control. If you started from.env.example, clearSOCKETIO_ADMIN_USERNAMEandSOCKETIO_ADMIN_PASSWORD_HASHor set your own. See Security. - Database. MongoDB on a private network only, with authentication when it is not on the same host or Docker network, and on an encrypted volume.
- Monitoring. Point your uptime checker at
/health. See Logs and monitoring.
AlianHub Cloud
On an instance hosted by AlianHub Cloud, the platform runs the server for you. The console there hides Backups, Upgrade and Logs, and shows the URL, mail, storage and security settings as managed. Most of this guide is about self-hosted instances.