The Projects page is where the dashboard opens. Every project on the server is there, with its domain, state and services. This guide uses the default Birch layout; Oak shows the same projects with a sidebar.
The projects page
Projects open on a canvas. Each card shows what the project serves, its domain, whether it is online, and its services. An arrow from one card to another means that project reads one of the other's variables.
The icons at the top right switch to cards or a table, and the choice is remembered. Search, or press Ctrl + K anywhere, to jump to a project, a page or an action.
Creating a project
New in the top bar opens the new project window. Pick where the project comes from on the left:
- GitHub: pick a repository from a connected GitHub account, deploy on every push and preview pull requests. See Connect GitHub.
- Git repository: any repository URL and branch. A private one takes an access token under Advanced.
- Docker image: an image from a registry.
- Template: a ready-made app, searchable by name.
- Compose file: paste your own
docker-compose.yml.
Give the project a name (lowercase letters, numbers and hyphens). Advanced holds the container port, domain, subdirectory of a repository, environment variables, a database and registry login.
Inside a project
Opening a project shows its services as a graph drawn from the Compose file: what depends on what, which domain points where, how many replicas are up, and which folder each service keeps its data in. Add sets up a new service, database, domain or volume.
The rail on the left holds the rest of the project:
| Section | What it holds |
|---|---|
| Architecture | The services graph above |
| Deployments | Every deploy with its commit, trigger, phase and logs; deploy the latest commit or roll back |
| Logs | Live logs from every service, with search and a service filter |
| Variables | Variables, references to other projects, and sealed secrets |
| Metrics | CPU, memory and network per service |
| Settings | General information, domains and SSL, databases, quick actions, backups, security, and the Compose and service.yml files |
| Files | The project directory: browse, edit, upload, and extract archives |
| Terminal | A shell in any running container |
| Migration | Track a move from an old server: transfer, sync, cutover and a DNS check |
Deployments
Each deploy is listed with its commit, what started it (a click, a push, a pull request or a rollback) and its phase. Open one to read its build and deploy output. Deploy latest deploys the newest commit of the branch, and Roll back on a past deploy deploys its revision again.
Variables and secrets
A variable can hold a value, reference another project's variable with ${{ plausible.BASE_URL }}, or reference a sealed secret with ${{ secret.NAME }}. The page shows what each reference resolves to. Secrets can be replaced or rotated but never read back.
Files and terminal
Files shows the project directory as it is on disk, including docker-compose.yml and service.yml. Terminal opens a shell in a container you pick.
Project actions
The project header has Diagnose, which checks each layer from the container to a public request, and Restart. The menu next to them holds the rest:
- Start and Stop: bring the services up or down. Data folders stay in place.
- Rebuild: build the project's images again without the cache, then recreate its services.
- Pull image: download newer images. Restart puts them to use.
- Delete: stop the project and remove its directory, including its data. Back it up first if you may need the data.
Domains
A project can serve several domains, each pointing at one of its services. Add one from Add on the graph or from Settings, with:
- Domain: the host name
- Service and port: where requests go
- Path prefix: serve only part of the site, optionally stripping the prefix
- SSL: issue and renew a certificate
- Aliases: more names for the same site, such as
www
FlatRun writes the proxy configuration, reloads it, and requests the certificate.
Each domain also has its own serving settings:
- Maximum upload request size: the largest request the domain accepts
- Timeout: how long a slow or quiet connection may stay open
- Streaming: send responses as the app writes them, for server-sent events
- Response headers: headers added to every response
- Alias redirect: send visitors on an alias to the primary domain
- Username and password, and an IP allow-list: limit who reaches the site
When the limit turns uploads away, the project shows how many, the limit, and a button that opens the domain at that field.
See Per-domain settings for what each one does.
Services
Open a service on the graph and choose Settings to set its CPU and memory limits, restart policy, log rotation, variables, command and entrypoint. FlatRun keeps them across redeploys and offers to recreate the service so it uses them.
The same tab can let a single service sleep when idle, such as a worker, while the rest of the project keeps running. A sleeping service shows as asleep on the graph.
See Service settings and Sleeping one service for the details.
Databases
Under Settings, a project can connect to several databases. Each has an alias, a type such as MySQL, PostgreSQL, MongoDB or Redis, and a mode:
- Shared: a database on a shared database server
- Container: a database service in this project
- External: a server elsewhere
With an env_prefix, FlatRun writes the connection into variables:
${PREFIX}_HOST${PREFIX}_PORT${PREFIX}_DATABASE${PREFIX}_USERNAME${PREFIX}_PASSWORD
Changing a project
Edit docker-compose.yml under Settings or in Files, then restart to apply it. A project built from Git changes by pushing to its branch, or with Deploy latest.