Skip to main content

Projects

Projects group related resources and provide isolation between environments.

What is a Project?​

A project is:

  • A namespace - Resources are isolated per project
  • An environment - Separate production, staging, development
  • A billing unit - Track costs per project
  • An access scope - Control member permissions per project

Project Structure​

Creating a Project​

Steps​

  1. Go to your organization dashboard
  2. Click Create Project
  3. Enter project name (e.g., "Production")
  4. Select a Location (provider and region)
  5. Click Create

Project Location​

When creating a project, you choose a location — a provider and region pair that determines where all resources in the project are deployed. The available locations are listed in the creation dialog.

warning

The location is permanent. Once a project is created in a given location, it cannot be moved. All containers, databases, and services in the project run in that location.

Naming Conventions​

Valid names:
production
staging
development
client-bigco
api-v2
My Project
my_project
project.1

Invalid names:
-project (starts with hyphen)
project- (ends with hyphen)
my--project (consecutive special chars)
Name Rules

Project names must start and end with an alphanumeric character. They can contain spaces, dots, hyphens, or underscores, but not consecutively. Names are unique per organization (case-insensitive) — you cannot create two projects named "Production" and "production" in the same organization. Deleted projects release their name for reuse, but projects pending deletion still reserve theirs.

Project Slug​

The slug is used in:

  • Internal URLs
  • DNS names
  • API calls
Project: Production Environment
Slug: production-environment

Internal DNS: {service-name}.{namespace}
Example: backend.production-environment-abc123

Project Dashboard​

Overview​

The project dashboard shows:

SectionInformation
ResourcesAll containers, databases, etc.
MetricsAggregate usage charts
AlertsActive alerts for this project
EventsRecent events

Resource Counts​

Quick view of resources:

Containers: 5 running, 1 stopped
Databases: 2 active
Gateways: 1 active
Cache: 1 active

Managing Projects​

Viewing Projects​

  1. From the organization dashboard
  2. See all projects in the grid or list
  3. Click a project to open it

Reordering projects​

You can reorder projects to control how they appear in the sidebar and the organization dashboard:

  1. Go to the Projects tab in your organization
  2. Click Reorder (requires the MAINTAINER or OWNER role)
  3. Drag projects into the desired order, or use the arrow buttons
  4. Click Save

The order is shared across the organization — every member sees the same order. New projects are added at the end. If a project is created or deleted while you are reordering, the save fails with a warning; the list refreshes automatically so you can reorder again.

Switching Projects​

  1. Click the project name in the header
  2. Select from the dropdown
  3. Or use the project switcher sidebar

Project Settings​

  1. Open your project
  2. Click Settings
  3. Configure options

Project Isolation​

Network Isolation​

By default, resources can only communicate within the same project:

✓ Container A → Database (same project)
✓ Container A → Container B (same project)
✗ Container A → Database (different project)
Cross-project access

You can create controlled exceptions to project isolation using Project Peerings. Peerings allow specific workloads in one project to reach a container service port in another project within the same organization.

DNS Resolution​

Internal DNS only resolves within the project. The format is {service-name}.{namespace}:

backend.my-project-abc123
my-database.my-project-abc123

Secrets and Config​

Environment variables and secrets are project-scoped:

API_KEY in Production ≠ API_KEY in Staging

Common Project Patterns​

Environment-Based​

Organization: MyCompany
├── production # Live environment
├── staging # Pre-production testing
└── development # Development environment

Team-Based​

Organization: BigCorp
├── frontend-team # Frontend resources
├── backend-team # Backend services
└── data-team # Data processing

Client-Based​

Organization: Agency
├── client-acme # Acme Corporation
├── client-bigco # BigCo Industries
└── internal # Agency's own projects

Product-Based​

Organization: SaaS Company
├── main-app # Primary product
├── analytics # Analytics platform
├── docs # Documentation site
└── blog # Company blog

Project Lifecycle​

Creating Projects​

Creation is asynchronous: the API accepts the project and answers 202 with it in the Provisioning phase. A background worker sets up its namespace and resources. The project moves to Active once everything is ready, or to Failed if the setup could not be completed.

While a project is provisioning, no resources can be created in it. The sidebar shows a pulsing clock icon, and the project dashboard displays a banner. If creation fails, the banner explains what to do — delete the project and create another one.

Best practices:

  • Use descriptive names
  • Select the right location (provider and region) — it is permanent
  • Wait for the project to become active before creating resources

Active Projects​

Keep projects organized:

  • Regular cleanup of unused resources
  • Monitor costs per project
  • Review access periodically

Failed Projects​

A project that could not be created stays listed in the Failed phase. It cannot hold any resources and will not be retried. Delete it from Settings > Advanced and create a new one.

Suspending and resuming projects​

Projects can be suspended, which scales all resources (containers, databases, caches, etc.) to zero replicas. This is useful for:

  • Cost savings — Suspended projects do not incur compute charges
  • Temporary deactivation — Pause a project without deleting it
  • Trial expiry — Projects may be automatically suspended when a trial ends

To resume a suspended project:

  1. Open the suspended project
  2. Click Resume Project
  3. Resources will be scaled back to their previous configuration
warning

While suspended, all containers, databases, and services are stopped. Persistent storage is retained, but no compute charges apply.

Deleting Projects​

A project must be empty before it can be deleted — remove its containers, databases and other resources first. If anything remains, the deletion is refused and the response lists what is left.

  1. Go to project Settings
  2. Open the Advanced tab
  3. Click Delete Project
  4. Type the project name to confirm
  5. Click Delete project

The project enters Pending Deletion state:

  • All workloads are immediately suspended (scaled to zero)
  • No new resources can be created
  • The project is scheduled for permanent deletion after a grace period
  • You can restore the project at any time before the deadline

Projects in the Provisioning or Failed phase can also be deleted.

warning

After the grace period, the project and its settings are permanently deleted and cannot be recovered. Logs, metrics and audit entries expire on their own retention schedule.

Immediate deletion​

If you do not need a grace period, check Delete this project and its settings now in the confirmation dialog. The project is removed at once — there is no deadline and no way to restore it afterwards. The project name becomes available for reuse immediately.

Restoring a deleted project​

If you change your mind, you can restore a project that is pending deletion before the deadline:

  1. Open the project (it will show a pending deletion banner)
  2. Click Restore Project
  3. The project is restored in a Suspended state while its workloads come back; it moves to Active a moment later
info

Restoring is not possible after an immediate deletion, or if the parent organization is archived. Resolve the organization's billing status first.

Project Quotas​

Default Limits​

ResourceLimit per Project
Containers100
Databases20
Gateways50
Cache instances20

Increasing Limits​

Contact support for higher limits.

Cost Tracking​

Per-Project Costs​

View costs for each project:

  1. Go to Organization > Billing
  2. View By Project breakdown
  3. Drill into specific resources

Cost Allocation​

Use projects for cost allocation:

Engineering Budget:
├── production €500/month
├── staging €100/month
└── development €50/month
Total: €650/month

Marketing Budget:
└── marketing-site €75/month
Total: €75/month

Access Control​

Project-Level Permissions​

Members can have different roles per project:

Alice:
├── production → Reporter
├── staging → Developer
└── development → Maintainer

Bob:
├── production → Maintainer
├── staging → Maintainer
└── development → Maintainer

Role Inheritance​

Organization owners have full access to all projects.

Best Practices​

1. Separate Environments​

Never mix production and development:

✓ Separate project for production
✓ Separate project for staging
✓ Separate project for dev

✗ All in one project

2. Consistent Naming​

Use a consistent naming scheme:

✓ prod, staging, dev
✓ production, pre-prod, development
✓ live, test, sandbox

✗ Mixed naming conventions

3. Document Projects​

Add descriptions explaining:

  • Project purpose
  • Team responsible
  • Key resources
  • Contact information

4. Regular Cleanup​

Monthly reviews:

  • Remove unused resources
  • Update documentation
  • Review access

5. Use Labels​

Tag resources for organization:

labels:
environment: production
team: backend
service: api