Projects

A project is one app on your server: a directory with a Docker Compose file. Each service in that file is a service of the project, and every time FlatRun brings the project up from a new revision it records a deployment.

A project is a directory

The agent watches its deployments path (/opt/flatrun/deployments on an installed server) and treats every subdirectory with a Compose file as a project. The directory name is the project's name and its id in the API.

/opt/flatrun/deployments/
├── shop/                     # Project "shop"
│   ├── docker-compose.yml    # Its services
│   ├── service.yml           # FlatRun settings: domains, SSL, health checks
│   ├── .env.flatrun          # Variables, written by the agent
│   └── data/                 # Data the services keep, as plain folders
├── blog/                     # Project "blog"
│   └── docker-compose.yml
└── .flatrun/                 # Agent state: deploy history, secrets, users

The app itself is all in its directory; FlatRun keeps only its own records, such as deploy history and sealed secrets, under .flatrun. Copy the directory to another server and docker compose up -d runs it there, with or without FlatRun.

docker-compose.yml

A standard Compose file. Keep data in bind mounts next to the file rather than in named volumes, so backups and moves are plain file copies.

services:
  web:
    image: wordpress:6.6-apache
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
    volumes:
      - ./data/wordpress:/var/www/html
    depends_on:
      - db

  db:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: wordpress
      MYSQL_PASSWORD: ${DB_PASSWORD}
    volumes:
      - ./data/mysql:/var/lib/mysql

service.yml

FlatRun's own settings for the project: how it is exposed, its domains, SSL and health checks. The dashboard writes it; you can edit it by hand.

name: blog
type: web
networking:
  expose: true
  domain: blog.example.com
  service: web
  container_port: 80
  protocol: http
ssl:
  enabled: true
  auto_cert: true
healthcheck:
  path: /
  interval: 30s

.env.flatrun

The project's variables, resolved and written by the agent before Compose runs. A variable can reference another project's variable or a sealed secret; the file holds the resolved values. FlatRun uses this name instead of .env so it never collides with an app's own .env.

Services

Each service in the Compose file is one service of the project. FlatRun shows them as a graph, with what depends on what, which domain points where, and how many replicas are up. Logs, metrics and restarts work per service.

Deployments

A deployment is one deploy of a project: which revision went out, what triggered it, how it went and its output. A deploy is started by hand, by a push to the project's branch, by a pull request preview, or by a rollback. It moves through queued, building and deploying; the newest successful one is active, and older ones read as removed.

FlatRun keeps the last 50 deployments of each project with their logs. Rolling back picks one and deploys its revision again.

Environments

A project built from a Git repository can have environments: a copy that follows its own branch, such as staging. An environment is a project of its own named after its base, shop-staging for shop, so it has its own directory, containers, domains and deployments. It starts with the base's variables and network attachments. Pull request previews are environments too.

Project states

State	Meaning
running	At least one container is running
paused	No container is running and at least one is paused
stopped	The project has no containers
unknown	Containers exist but none is up, for example while restarting

Creating a project

• From a Git repository: FlatRun clones it, builds it when needed, and can deploy on every push.
• From an image: one service running a published image.
• From a Compose file: paste or upload your own.
• From a template: a ready-made Compose file for a common app.
• By hand: create a directory with a Compose file in the deployments path; the agent picks it up.

Deleting a project

Deleting a project stops and removes its containers, then removes its directory, including the data folders inside it. Its certificate and proxy configuration go with it by default; a database it created on a shared database server is kept unless you ask for it to be removed. Back up the directory first if you may need the data.