# Projects

A project connects a Git repository to orkestr. When you create one, orkestr clones the repo, detects the framework, builds a Docker image, and deploys it as a long-running container with a public URL. Push to the repo and it redeploys automatically. A project is the right primitive when you have an actual application to run; for a single endpoint reach for a [function](https://orkestr.eu/docs/features/functions) instead.

## Creating a project

1. Connect a Git provider (GitHub, GitLab, Bitbucket, or Codeberg) under **Settings**. This is a one-time, account-level authorization.
2. Go to **Projects -> New Project** and pick a repository and a branch.
3. orkestr analyzes the repo: it detects the framework and runtime, picks a port, and generates a production Dockerfile if your repo doesn't already have one.
4. The first deploy builds the image and brings the app up at `{project}.orkestr.run`.

Project slugs are globally unique because they map to a subdomain. Names must match `^[a-z0-9][a-z0-9-]*$` - lowercase letters, digits, and hyphens, starting with a letter or digit.

## Framework detection and the Dockerfile

On every deploy, the analyze step inspects your repo and figures out how to build and run it. Supported frameworks include Next.js, Nuxt, React (CRA/Vite), Vue, FastAPI, Flask, Django, Express, NestJS, Spring Boot, Go, and static sites. Each has a production-ready, multi-stage Dockerfile template that builds a small final image and runs as a non-root user.

- **No Dockerfile in the repo:** orkestr generates one for the detected framework.
- **Dockerfile present:** orkestr uses yours as-is, so you keep full control of the build.
- **Monorepo:** a build context subdirectory is detected so the build runs from the right folder.

> **Bring your own Dockerfile**
>
> If detection ever picks the wrong thing, commit a Dockerfile to the repo. orkestr always prefers an existing Dockerfile over a generated one, which makes builds fully deterministic.

## Environment variables

Variables are set per environment and injected into the container at deploy time. They are encrypted at rest. Changing a variable requires a redeploy to take effect. Names beginning with `ORKESTR_` are reserved for the runtime.

```bash
DATABASE_URL=postgres://...
SECRET_KEY=change-me
NODE_ENV=production
```

## Auto-deploy on push

When you create a project, orkestr registers a webhook with your Git provider. Pushing to a branch that matches an environment triggers a new build and deploy for just that environment. Production tracks your default branch; add more [environments](https://orkestr.eu/docs/features/environments) to map other branches (staging, previews).

## What a project gives you

- **Environments** - production is created automatically; add more per branch on paid plans.
- **Deployments** with live logs and rollback - see [Deployments](https://orkestr.eu/docs/features/deployments).
- **Custom domains** with automatic TLS - see [Domains](https://orkestr.eu/docs/features/domains).
- **Add-ons** - managed Postgres or Redis on a private network - see [Add-ons](https://orkestr.eu/docs/features/addons).
- **Jobs** - run one-off commands in the project image - see [Jobs](https://orkestr.eu/docs/features/jobs).
- **Monitoring** - CPU, memory, requests, and logs - see [Monitoring](https://orkestr.eu/docs/features/monitoring).

## Security and isolation

Builds run in an isolated, resource-limited build sandbox with no access to the host or other tenants, and are time-boxed. The app container then runs hardened: all Linux capabilities dropped, no new privileges, a PID limit, and CPU/memory caps. User containers run on an isolated network and cannot reach the platform's database, registry, or other tenants' containers.

## Plan limits

- **Starter (free):** 1 project, 1 environment, auto-deploy, community support.
- **Pro:** 5 projects included (then €4/project/mo), 3 environments each, rollbacks, custom domains, add-ons, API access.
- **Pro:** per-seat team members - invite collaborators into a shared workspace at €15/seat.
- **Enterprise:** custom project limits, unlimited environments, monitoring + alerts, dedicated nodes.

> **Idle apps sleep**
>
> On free and Pro, idle containers auto-sleep after a period of no traffic and wake on the next request (the first request after sleep is a little slower). Pro and Enterprise apps stay always-on.

## FAQ

### Can I deploy a private repo?

Yes. The connection you authorize grants orkestr access to clone your private repositories for building.

### How do I change the branch a project deploys?

Each environment has its own branch. Edit the environment to point it at a different branch; the next push (or a manual deploy) picks it up.

### What port does my app need to listen on?

orkestr detects the port from your framework or Dockerfile and routes to it. If you use a custom Dockerfile, expose the port your app listens on.

### How do I delete a project?

Deleting a project tears down its containers and routing. Any cron that targeted one of its jobs is paused automatically.