Project

Contains

Applications · Compose stacks · Managed databases

Shares

Database references + shared variable sets

Access

Member list + role per project

What a project groups together

shop/                      ← project (uses the variable sets shared with it)
├── shop        application  Next.js, domain shop.example.com
├── worker      application  queue worker, no domain
├── app-db      database     PostgreSQL 16
├── cache       database     Redis 7
└── monitoring  stack        docker-compose (grafana + loki)

One project, or several?

• One project per product/environment: shop, shop-staging — databases and access stay cleanly separated. You don't need extra projects just for development/staging variables — use the environments of a variable set.
• Applications that share a database must be in the same project so they can reference it.
• Database slugs are global (unique across projects) — give them specific names, e.g. shop-db, not db.

Creating a project

1. Projects menu → New project

   Field	Description
   Name	E.g. my-app. Its slugified form becomes part of the image name in the registry (<registry>/<project>/<app>:<tag>); renaming a project after there's been a deployment makes the next image use a new repository — the old one stays around.
   Description	Optional, shown in the project list.

2. The project detail page

   Three sections — Applications, Compose stacks, Databases — each with an add button (New application, New compose stack / From template, New database) and a brief status for each item. The Settings tab handles name, description, members, the variable sets shared with the project, and deleting the project.

Variables

Projects no longer have environments of their own. Shared variables live in variable sets: an instance owner or admin creates a set (with environments such as development, staging and production) and shares it with all projects or with selected ones. Applications and stacks of the project then link set environments, in order, on their Environment tab and reference values with ${{vars.KEY}}.

• The project's Settings tab lists the sets shared with it and which of its applications and stacks use them.
• Your project role decides what you may do with a set's values: developers and project admins reveal and edit unprotected environments, viewers see names only, and protected environments are for instance owners and admins. Linking or unlinking a protected environment needs the project admin role.
• Upgrading from 0.1.0-alpha.9: a project whose environments had content became one set named after the project, shared with it only; see the upgrade note.

Project members

The Members tab on the project page decides who can see and change this project. Add someone by the email of an existing account, then choose a role:

• The project's creator automatically becomes a project admin; the instance owner and admins see every project without being added.
• Other instance members only see projects they've been added to — other projects return 404. Details in Users & roles.

Export & import a project

The Export configuration (JSON) button on the project page downloads a portable definition: applications, databases, compose stacks along with their domains, mounts, jobs, and backup schedules. References to things outside the project (server, registry, Git credentials, S3 destination) are carried by name. Applications and stacks keep their variable set links (set and environment names, in order); on import an existing set with that name is reused, never overwritten. Files from 0.1.0-alpha.9 and older become one variable set named after the new project. Details in Variables.

1. Import on another instance

   Projects → Import project: choose the file, give it a new name or use the one from the file.

2. Check the warnings

   A slug is reused if it's still free; conflicting host ports or domains, and references that can't be found, are reported as Needs review — not a failure. Databases are provisioned in the background; jobs and backup schedules are registered right away.

On the Dashboard

The Dashboard shows a summary: how many projects have something running (an application, database, or stack) and a list of recent projects with a See all link.

Ownership & access

• A project records its creator, who is always its project admin. Who else can see it is decided by the member list above — see Users & roles.
• A user who still owns a project can't be removed from the team — delete their project first (ownership can't yet be transferred from the UI).
• Every project change is recorded in the audit log.

Deleting a project

Deleting a project removes everything in it: its applications, compose stacks, and databases are stopped and their containers removed (so their domains stop working), and then their records, backups history, and the project itself are deleted. The delete dialog has an Also delete data checkbox, unchecked by default.

If aoox cannot reach the Docker daemon (or a remote server) while removing something, the delete stops with an error that names it. The project and whatever was not removed yet stay, so you can fix the connection and delete again. Only project admins can delete a project.

Deleting a single application also removes its blue/green candidate container, and is refused (the application is kept) when its Docker daemon cannot be reached, instead of leaving the container running.

Common pitfalls

Next steps