Deployments

A deployment is the fundamental unit of work in FlatRun. Each deployment represents a set of Docker containers defined by a docker-compose file, along with associated metadata and configuration.

What is a Deployment?

In FlatRun, a deployment is simply a directory containing a docker-compose.yml file. The agent monitors a designated deployments directory and automatically discovers any subdirectories with valid compose files.

/var/flatrun/deployments/          # Deployments root
├── my-wordpress/                   # Deployment: "my-wordpress"
│   ├── docker-compose.yml          # Required: Container definitions
│   ├── service.yml                 # Optional: FlatRun metadata
│   ├── .env.flatrun                # Auto-generated by agent
│   └── data/                       # Optional: Persistent data
├── my-api/                         # Deployment: "my-api"
│   └── docker-compose.yml
└── nginx/                          # Infrastructure deployment
    ├── docker-compose.yml
    └── conf.d/                     # Nginx configuration

Deployment Structure

docker-compose.yml (Required)

The standard Docker Compose file that defines your services, networks, and volumes. FlatRun supports Compose file versions 2.x and 3.x.

version: "3.8"
services:
  app:
    image: wordpress:latest
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_NAME: wordpress
    volumes:
      - wp_data:/var/www/html
    depends_on:
      - db

  db:
    image: mariadb:10
    environment:
      MYSQL_DATABASE: wordpress
      MYSQL_ROOT_PASSWORD: secret
    volumes:
      - db_data:/var/lib/mysql

volumes:
  wp_data:
  db_data:

service.yml (Optional)

FlatRun-specific metadata that configures how the deployment is exposed and managed:

name: My WordPress Site
type: application

networking:
  expose: true
  domain: blog.example.com
  port: 8080

ssl:
  enabled: true
  auto_renew: true

health_check:
  enabled: true
  path: /wp-admin/install.php
  interval: 30s

.env.flatrun File (Auto-generated)

The agent automatically generates .env.flatrun when creating deployments with environment variables or shared database connections. This file is passed to Docker Compose at runtime. FlatRun uses .env.flatrun instead of .env to avoid conflicts with applications that mount their own .env files.

# Auto-generated by agent
DB_HOST=flatrun-mysql
DB_NAME=myapp
DB_USER=myapp_user
DB_PASSWORD=generated_password

Deployment States

A deployment can be in one of the following states:

Deployment Lifecycle

Creating a Deployment

Deployments can be created in several ways:

1. From Template — Select a pre-built template from the UI or API
2. Custom Compose — Write your own docker-compose.yml
3. Manual — Create a directory with a compose file in the deployments path

Starting a Deployment

When you start a deployment, FlatRun:

1. Validates the docker-compose.yml syntax
2. Pulls any missing images
3. Creates networks and volumes
4. Starts all defined services
5. Optionally configures the reverse proxy

Stopping a Deployment

Stopping a deployment gracefully shuts down all containers while preserving:

• Named volumes (persistent data)
• Configuration files
• Network definitions

Deleting a Deployment

Deleting a deployment:

1. Stops all running containers
2. Removes containers and networks
3. Optionally removes the deployment directory
4. Does NOT remove named volumes (data preservation)

Services Within a Deployment

Each service defined in the docker-compose.yml becomes a container when the deployment is started. FlatRun tracks each service individually, allowing you to:

• View logs for specific services
• Monitor resource usage per service
• Restart individual services without affecting others

Networking

FlatRun creates isolated Docker networks for each deployment. Services can also connect to shared networks like the proxy network for external access.

networks:
  default:              # Deployment-internal network
  proxy:                # Shared proxy network
    external: true

File Management

FlatRun provides file management capabilities for each deployment:

• Browse — Navigate the deployment directory structure
• View/Edit — Read and modify configuration files
• Upload — Upload files to the deployment
• Download — Download files from the deployment

Best Practices

• Use Named Volumes — Always use named volumes for data that should persist
• Descriptive Names — Use clear, descriptive deployment names
• Environment Variables — Pass secrets via the API, not hardcoded in compose files
• Health Checks — Configure health checks for production deployments
• Resource Limits — Set memory and CPU limits to prevent resource exhaustion