# Getting started

End-to-end tour of the platform. Connect a repo, deploy your first app, set up environments, attach a database, point a custom domain, and learn how to roll back when something breaks. Each step corresponds to a page in the console - keep this open in a second tab as you go through.

> **Your code stays yours**
>
> orkestr does not store your source code. During deployments your repository is cloned temporarily to build a Docker image and then automatically deleted - whether the build succeeds or fails. Only the compiled image is retained to run your app. When you delete a project everything is permanently removed: containers, images, logs, and configuration.

## Plans at a glance

Each plan limit is enforced at the resource level (create, deploy, rollback) and surfaced inline in the console when you hit it.

| Feature | Free | Pro | Enterprise |
| --- | --- | --- | --- |
| Projects | 1 | 5, then €4 ea | Custom |
| Environments per project | 1 | 3 | Unlimited |
| Add-ons per project | 1 | 2 | 5+ |
| Groups | - | Yes | Yes |
| Rollbacks | - | Yes | Yes |
| API access | 1 token | 5 tokens, 100 req/min | Custom |
| Backup retention | - | 7 days | 30 days |

## 1. Connect a Git provider

Link your GitHub, GitLab, Bitbucket, or Codeberg account so orkestr can access your repositories.

1. Go to **Settings** from the sidebar.
2. Scroll to **Connected Providers**.
3. Click the provider you want to connect (e.g. GitHub).
4. Authorize orkestr via the OAuth flow on the provider's site.
5. You'll be redirected back - the provider now shows **Connected** with your username.

> You can connect multiple providers at once. You can also enter a repository URL manually when creating a project if you prefer not to connect an account.

## 2. Create a project

A project represents a single app or service linked to a Git repository.

1. Navigate to **Projects** and click **New Project**.
2. Pick a repository from your connected providers, or paste a repo URL manually.
3. orkestr auto-detects the framework, port, and Dockerfile. For monorepos it lists each service - pick the one you want to deploy.
4. Review the auto-generated **name**, **slug** (used in your URL, e.g. `my-app.orkestr.run`), **branch**, and **description**. Edit any field if needed.
5. Click **Create Project**.

> **Plan limits**
>
> Free: 1 project. Pro: 5. Enterprise: custom.

## 3. Add environment variables

Most apps need configuration like database URLs, API keys, or feature flags. Set these before your first deploy so the app starts correctly.

1. Open your project and click into the environment you want to configure (e.g. **production**).
2. Scroll to **Environment Variables**.
3. Add key-value pairs (e.g. `DATABASE_URL`, `SECRET_KEY`).
4. Values are **encrypted at rest** and masked in the dashboard. They are injected into your container at runtime.

> Each environment has its own set of variables. Your staging environment can point to a different database than production. Add-ons like PostgreSQL and Redis automatically inject their connection URLs.

## 4. Deploy your app

Trigger a deployment to build a Docker image from your repo and run it on orkestr's infrastructure.

1. Open your project and select the environment you want to deploy (defaults to **production**).
2. Click the **Deploy** button.
3. orkestr clones your repo, builds a Docker image, and starts the container.
4. Follow the build pipeline in real time - each step (clone, build, push, deploy) shows live logs.
5. Once the status shows **Live**, your app is running at its `slug.orkestr.run` URL.

> **Auto-deploy**
>
> Enable auto-deploy on any environment so pushes to its branch trigger a deployment automatically. Requires a connected Git provider.

## 5. Set up environments

Environments let you run the same project from different branches - e.g. production, staging, and dev - each with its own URL, env vars, and deploy history.

1. Open your project and scroll to **Environments**.
2. Click **+ Add Environment**.
3. Enter a **name** (e.g. `staging`) and the **branch** it should deploy from (e.g. `develop`).
4. Click create. The environment gets its own subdomain (e.g. `my-app-staging.orkestr.run`).
5. Click into the environment to configure **environment variables**, toggle **auto-deploy**, or trigger a deployment.

> **Plan limits**
>
> Free: 1 environment. Pro: 3 per project. Enterprise: unlimited. The production environment cannot be deleted.

## 6. Create a group

Groups connect multiple projects on a private network so they can talk to each other via internal DNS - perfect for a frontend + API + worker setup.

1. Navigate to **Groups** and click **New Group**.
2. Enter a **name** and optional **description**. The slug auto-generates.
3. Click **Create Group**.
4. On the group detail page, click **Add Service** and select the projects you want to include.
5. Services in a group can reach each other at `http://project-name:port` on the private network.

> Groups are available on the Pro plan. A project can only belong to one group at a time. Deleting a group disconnects its projects but does not delete them.

## 7. Add a database or cache

Provision a managed PostgreSQL database or Redis cache and have the connection string automatically injected as an environment variable.

1. Navigate to **Add-ons** and click **Add Service**.
2. Select the **project** the add-on belongs to and optionally assign it to a **group** for private networking.
3. Enter a **name** (e.g. `main-db`) and choose **PostgreSQL** or **Redis**.
4. Click **Create Add-on**. The connection URL is injected as `DATABASE_URL` or `REDIS_URL`.
5. Manage backups from the add-on card - trigger manual backups, download, or schedule automatic ones.

> **Plan limits**
>
> Free: 1 add-on. Pro: 2 per project. Enterprise: 5+ per project. Deleting an add-on permanently destroys its data.

## 8. Configure a custom domain

Point your own domain to any project. orkestr handles TLS certificates automatically.

1. Navigate to **Domains** and find your project.
2. Click **Add domain** and enter your custom domain (e.g. `app.yourdomain.com`).
3. Click **Save**. The status will show **Pending DNS**.
4. At your DNS provider, add a **CNAME** record pointing to your project's default domain (shown in the instructions).
5. Click **Verify DNS**. Once propagation completes (usually minutes, up to 48 hours), the status changes to **Active** and your domain is live.

> For root domains (e.g. `yourdomain.com`), use an ALIAS or ANAME record if your DNS provider supports it - CNAME is not standard for root domains.

## 9. Monitor your app

Keep an eye on your running containers with built-in monitoring for CPU, memory, logs, and health.

1. Navigate to **Monitoring** from the sidebar.
2. **Stats** - view real-time CPU usage, memory consumption, and network I/O per container.
3. **Logs** - stream your application's stdout/stderr output with configurable line count.
4. **Health** - check container status, uptime, and restart count at a glance.

> **Alerts**
>
> orkestr sends real-time notifications when a deployment fails or when CPU / memory usage spikes above thresholds.

## 10. Roll back a deployment

If a deployment introduces a bug or breaks your app, you can instantly revert to a previous working version.

1. Open your project and go to the environment with the broken deployment.
2. In the deployment history, find the last deployment that was working (status **superseded**).
3. Click **Rollback** on that deployment.
4. orkestr restarts your container with the previous Docker image - no rebuild required, so it's near-instant.

> Rollbacks are available on the Pro plan. You can also trigger rollbacks via the [API](https://orkestr.eu/docs/api-reference), [CLI](https://orkestr.eu/docs/cli), or [MCP server](https://orkestr.eu/docs/mcp) for automated recovery workflows.

## 11. Generate an API token

API tokens let you interact with orkestr programmatically - from CI/CD pipelines, the CLI, or MCP-connected AI assistants.

1. Go to **Settings** and switch to the **API** tab.
2. Enter a **name** for the token (e.g. `CI/CD Pipeline`) and choose an optional **expiry** (30, 90, 180, 365 days, or never).
3. Click **Create Token**.
4. Copy the token immediately - it is only shown once and cannot be retrieved later. Tokens are hashed before storage.

> **Plan and scope**
>
> API tokens are available on every plan - Starter (1 token), Pro (up to 5), and Enterprise (custom). For sandbox-only workloads, mint tokens with the `sandboxes:read` / `sandboxes:write` scopes so the token cannot reach the rest of the platform if it leaks.

## 12. Create a serverless function

Paste a handler, pick a runtime, get a public URL in seconds. No Dockerfile, no repo - the platform wraps your code in a tiny HTTP server, builds the image, and runs it as a scale-to-zero container.

1. Navigate to **Functions** and click **New Function**.
2. Enter a **slug** (e.g. `stripe-webhook`) - this maps to `fn-stripe-webhook.orkestr.run`.
3. Pick a **runtime**: Node.js 20 or Python 3.12.
4. Choose **auth**: *public* (for webhook receivers) or *API key* (auto-generated, sent as `X-Orkestr-API-Key` or `Authorization: Bearer`).
5. Paste your **handler code**. The event object has `method`, `path`, `query`, `headers`, and `body`.
6. Click **Create function**, then **Save & Deploy** on the detail page. Build takes ~10 seconds.
7. Use the **Test** tab to invoke with custom method, path, body, and headers - response, duration, and status are shown inline.
8. Watch live container output in the **Logs** tab. The **Settings** tab shows which node it landed on and lets you rotate the API key.

### Node.js example

```javascript
// Node.js 20 - echo the request back
exports.handler = async (event) => {
  return { method: event.method, path: event.path, query: event.query };
};
```

### Python example

```python
# Python 3.12 - same thing
def handler(event):
    return {"method": event["method"], "path": event["path"]}
```

> **Scale to zero**
>
> Functions sleep after idle (default 60s) and wake on the next request - first hit pays a ~1-2s cold start, subsequent hits are under 50ms. Higher CPU = faster cold start: ~3s Free, ~1.7s Pro for Python. Resources are re-synced from your plan on every deploy.

## Next steps

- [REST API reference](https://orkestr.eu/docs/api-reference) - script everything you did in the console
- [CLI](https://orkestr.eu/docs/cli) - the same surface from your terminal
- [MCP server](https://orkestr.eu/docs/mcp) - connect Claude Code, Cursor, or any MCP client
- [Workflow examples](https://orkestr.eu/docs/workflows) - PR previews, CI/CD, rollback scripts, batch ops
- [Sandboxes](https://orkestr.eu/docs/sandboxes) - hardware-isolated VMs for AI agents