DocsStart here
aoox documentation
A complete guide to installing and using aoox: from installing it on your own server to deploys, databases, backups, and notifications.
What is aoox?
aoox is a self-hosted PaaS built on Docker. You run it on your own server, then from the web dashboard you can deploy applications from a Git repo, create databases, set up domains, view logs, schedule backups, and receive notifications — without touching docker by hand.
Architecture
Three core containers run from a single compose file. Everything you create from the dashboard — applications, databases, registry, proxy, compose stacks — is just a regular Docker container on the same host, on the aoox network. There are two ways to add more machines: a remote server over SSH, or Docker Swarm to spread replicas of one application.
Core concepts
| Term | Meaning |
|---|---|
| Project | A container for related applications, compose stacks, and databases. |
| Variable set | Shared variables with their own environments (development, staging, production), shared with projects and linked to applications and stacks in order. |
| Application | A single Git repo that gets built, or a ready-made image, run as a container (or a Swarm service). |
| Deployment | One build → push → start run for an application. Has its own log and status; can be rolled back. |
| Compose stack | A docker-compose file from a repo (or a template) run as a set of containers. |
| Managed database | A PostgreSQL/MySQL/MariaDB/Redis container created and backed up by aoox. |
| Server | Another host connected over SSH as an additional deploy target, with its own proxy and volume backups. |
| Node (Swarm) | A machine in a Docker Swarm cluster; applications in service mode are spread across these nodes. |
Quick path
Install & create the owner account
Installation → open
/setup.Provision the local registry (and the proxy if you'll use a domain)
The Registry and Settings → Reverse proxy menus. The registry is required before the first deploy — Registry.
Create a project, then an application from a Git repo
Projects → New project → New application, click Deploy — Creating an application.
Add what you need
Domain, database, backups, webhook, notifications — all per application/project, from the dashboard.
Documentation map
- Start from a fresh VPSA complete walkthrough from a brand-new VPS to the panel on your own domain.
- InstallationRunning aoox on your own server with Docker Compose.
- Domain for the panelServe the dashboard and API on your own domain with HTTPS.
- Users & rolesFirst owner account, invitations, per-role limits, 2FA, API tokens, audit log.
- ProjectThe container for apps, databases, and compose stacks.
- Creating an applicationFrom a Git repo or a ready-made image, plus deploy modes.
- How builds workDockerfile, Nixpacks, or a static site, plus build args.
- Deploy & rollbackThe deploy flow, realtime logs, health checks, blue/green, rollback.
- Environment variablesApplication env, secret source, and database references.
- VariablesShared variable sets: environments, sharing, linking order, ${{vars.KEY}}.
- MountsVolumes, bind mounts, and config files for apps and databases.
- Scheduled jobsCron commands for applications, databases, and compose stacks.
- Webhook auto-deployAutomatic deploy on push from GitHub/GitLab.
- Pull request previewsA temporary container per PR with its own subdomain.
- Compose stacksDeploy a multi-service docker-compose stack from a repo.
- One-click templatesWordPress, Ghost, n8n, and more in a few clicks.
- Managed databasesRun PostgreSQL, MySQL, MariaDB, or Redis as a managed database per project.
- Data browserBrowse tables and run queries from the dashboard.
- Database admin UIAdminer, phpMyAdmin, pgAdmin, and more, installed in one click.
- Backup & restoreBack up databases and volumes, schedules, retention, S3 destinations.
- RegistryA local registry for built images, and external registries.
- Proxy & domainTraefik, application domains, automatic HTTPS, DNS checks.
- Custom SSL certificatesYour own certificate (corporate CA, wildcard) instead of Let's Encrypt.
- Cloudflare DNSAutomatic DNS records for application domains and wildcard certificates via DNS-01.
- Proxy configurationYour own Traefik middlewares (basic auth, headers, rate limit) attached per domain.
- Remote serversDeploy to another server over SSH.
- Docker SwarmMulti-node: applications as a service with replicas.
- Web terminalA shell into the host or a remote server, from the browser.
- MonitoringHost and container metrics, resource limits.
- NotificationsSend deploy and health alerts to Telegram, Slack, Discord, a webhook, or email.
- TroubleshootingCommon problems and how to fix them.
Found a mistake? Edit this page on GitHub ↗