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
- Go to your organization dashboard
- Click Create Project
- Enter project name (e.g., "Production")
- Select a Location (provider and region)
- 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.
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)
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:
| Section | Information |
|---|---|
| Resources | All containers, databases, etc. |
| Metrics | Aggregate usage charts |
| Alerts | Active alerts for this project |
| Events | Recent 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
- From the organization dashboard
- See all projects in the grid or list
- Click a project to open it
Reordering projects
You can reorder projects to control how they appear in the sidebar and the organization dashboard:
- Go to the Projects tab in your organization
- Click Reorder (requires the MAINTAINER or OWNER role)
- Drag projects into the desired order, or use the arrow buttons
- 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
- Click the project name in the header
- Select from the dropdown
- Or use the project switcher sidebar
Project Settings
- Open your project
- Click Settings
- 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)
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:
- Open the suspended project
- Click Resume Project
- Resources will be scaled back to their previous configuration
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.
- Go to project Settings
- Open the Advanced tab
- Click Delete Project
- Type the project name to confirm
- 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.
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:
- Open the project (it will show a pending deletion banner)
- Click Restore Project
- The project is restored in a Suspended state while its workloads come back; it moves to Active a moment later
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
| Resource | Limit per Project |
|---|---|
| Containers | 100 |
| Databases | 20 |
| Gateways | 50 |
| Cache instances | 20 |
Increasing Limits
Contact support for higher limits.
Cost Tracking
Per-Project Costs
View costs for each project:
- Go to Organization > Billing
- View By Project breakdown
- 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