# Projects, environments and services

> How Falak groups services into projects and environments, what the canvas shows, how groups and references work, and how to duplicate an environment.

Source: https://falak.sh/docs/concepts/projects-environments-services/

Falak organizes your apps like Railway: an organization has **projects**, each project has **environments**, and each environment holds **services** on a **canvas**. This page explains each level and the rules that apply.

## Projects

A project groups everything one product needs: its web app, workers, databases and third-party tools.

- Every organization has a **Default** project. Sites and databases created without a placement (for example through the API or CLI) land in its `production` environment.
- A new project is created with a `production` environment.
- Only **empty, non-default** projects can be deleted.

The **Projects** dashboard shows a card per project with a preview of its production services and their health (`4/4 services online`). Star a project to pin it first.

## Environments

An environment is an isolated set of services inside a project, for example `production` and `staging`.

- Each environment has a name and a slug (`production`, `staging`). Renaming changes the slug.
- The production environment cannot be deleted. Other environments can be deleted when they are empty.
- **Variable references resolve only within the same environment.** A staging site referencing `${{ db.DATABASE_URL }}` uses the staging `db` service.

### Duplicating an environment

Create an environment **from** an existing one to get a copy of its sites:

| Copied | Not copied |
|---|---|
| Site configuration, deploy script, Laravel toggles, shared paths, variables, canvas position and service name | Servers (pick servers per service afterwards), databases, push-to-deploy (turned off) |

Use this to create staging from production, then assign staging servers and create staging databases.

## Services

A service is a card on the canvas. It is one of two kinds:

| Kind | What it is |
|---|---|
| **Site** | A deployable app: Git repository, Docker image, Compose file, or template |
| **Database** | A database on a database-capable server (PostgreSQL, MySQL or MariaDB) |

Service names are unique within an environment. The name is what references use: a service called `Shop DB` is referenced as `${{ shop-db.KEY }}` (names match case-insensitively; spaces, dots and underscores count as dashes).

### The service card

Each card shows the service icon and name, its domain (sites) or engine and server (databases), the live status (`● Online`, `● Deploying 64%`, `● Failed`), and the servers it runs on. The leader server has a star. Services with persistent storage show a volume strip under the card.

### The service panel

Click a card to open its panel over the canvas. Site panels have these tabs:

| Tab | Contents |
|---|---|
| **Deployments** | Running, queued, active and past deployments; **View logs**; redeploy and rollback |
| **Variables** | Environment variables with reveal, raw editor and the reference picker |
| **Metrics** | CPU, memory, requests, latency and errors per server |
| **Logs** | Live application logs |
| **Observability** | Issues, slow routes, jobs and queries, heartbeats for this site |
| **Processes** | Web process, workers, Horizon, Octane, daemons, cron jobs |
| **Services** | Compose sites only: one row per Compose service |
| **Settings** | Source, Compose, Build, Deploy, Networking, Servers, Laravel, Commands, Danger zone |

Database panels have **Overview**, **Databases & users**, **Backups** and **Settings**.

Some tabs of the service panel open the site's full page (`/sites/{id}`, **Open classic page**) while the panel is being completed. The site page has the tabs **Overview**, **Deployments**, **Releases**, **Domains & TLS**, **Routing**, **Environment**, **Deploy script**, **Queues**, **Daemons**, **Scheduler**, **Commands**, **Deploy settings** and **Settings**. These docs name the panel location; the same settings live under the matching tab of the site page.

Panels are deep-linkable: `/projects/{project}/{environment}/service/{kind}/{id}/{tab}`. Press <kbd>Esc</kbd> to close the top panel and <kbd>[</kbd> / <kbd>]</kbd> to switch tabs.

## References and arrows

When a site's variables contain `${{ other-service.KEY }}`, Falak draws a dashed arrow to `other-service`. Compose `depends_on` relations are drawn the same way. Arrows are derived from configuration; you cannot draw them by hand. See [Variable references](/docs/guides/variable-references/).

## Groups

Groups are translucent frames around related cards:

- **Compose sites** are always drawn as a group: one card per Compose service with its own status, image and volumes.
- **User groups**: select cards (<kbd>⇧</kbd>-drag a box, or <kbd>⌘</kbd>/<kbd>Ctrl</kbd>-click), then click **Group**. Drop a card on a frame to add it; drag it out to remove it. Groups can be collapsed, renamed and ungrouped.

Groups only affect layout. They do not change networking or permissions.

## Canvas controls

| Action | How |
|---|---|
| Create a service | **+ Create**, <kbd>⌘K</kbd> → Create, or right-click the canvas |
| Pan | Drag, or <kbd>Space</kbd> + drag |
| Zoom | <kbd>⌘</kbd> + scroll, <kbd>+</kbd> / <kbd>-</kbd>, **fit** |
| Undo / redo layout changes | <kbd>⌘Z</kbd> / <kbd>⇧⌘Z</kbd> |
| Recent activity | **Activity** toggle |

Positions are saved per environment.

## API

Projects and environments are available in the REST API: [Projects API](/docs/api/projects/).

## Limits

- Redis and Valkey instances reach sites on other servers of the environment only over a shared private network (never a public address), and have no backups yet. See [Redis and Valkey](/docs/databases/redis-and-valkey/#limits).
- Duplicated environments get sites **without servers**; assign servers per service.
- The canvas has no "crashed" status for sites yet (compose services do report crashed containers).

## Next steps