Projects, environments and 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.

The site page

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.

Tip

Panels are deep-linkable: /projects/{project}/{environment}/service/{kind}/{id}/{tab}. Press Esc to close the top panel and [ / ] 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.

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 (⇧-drag a box, or ⌘/Ctrl-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, ⌘K → Create, or right-click the canvas
Pan	Drag, or Space + drag
Zoom	⌘ + scroll, + / -, fit
Undo / redo layout changes	⌘Z / ⇧⌘Z
Recent activity	Activity toggle

Positions are saved per environment.

API

Projects and environments are available in the REST API: Projects API.

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.
• 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

Manage projects and environmentsStep-by-step: create a staging environment.

Sites and runtimesWhat a site is and how it runs.