Projects and environments

Projects

A project groups the services that make up one application: for example a frontend, an API, a worker and a PostgreSQL database. Services in the same project and environment can reach each other over the private network and reference each other's variables.

The project canvas (Architecture tab) shows the services and how they connect. Observability shows logs across services, and Settings holds the project name, description and region.

Environments

Every project starts with a production environment. An environment is an independent copy of all the project's services, with its own:

• variables and shared variables,
• domains,
• deployments, replicas and volumes,
• private network (services in staging cannot reach services in production).

The set of services is shared: adding a service to the project adds it to every environment, where it starts inactive until you deploy it.

Creating an environment

Create an environment from the environment switcher in the project. You can start it empty or fork an existing environment: forking copies the services' settings, source overrides (such as the branch), variables and shared variables. Domains, volumes and data are not copied.

A common setup is a staging environment that deploys a develop branch while production deploys main.

Deleting an environment needs the admin role and removes its services, domains and volumes.

Shared variables

Each environment has shared variables that any service in it can reference with ${{shared.NAME}}. See Variables and references.