Services

Services are the individual containers that make up a deployment. Each service defined in your docker-compose.yml becomes a running container that FlatRun monitors and manages.

Services vs Containers

In FlatRun terminology:

• Service — A container definition in docker-compose.yml
• Container — A running instance of a service

A deployment typically contains one or more services. For example, a WordPress deployment might have:

• wordpress service — The WordPress application
• db service — The MySQL database
• redis service — Optional caching layer

Service Properties

Each service has the following properties tracked by FlatRun:

Container States

Containers can be in one of these states:

Health Checks

Docker health checks allow you to verify that your service is functioning correctly. Configure health checks in your docker-compose.yml:

services:
  web:
    image: nginx
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Health check states:

• starting — Container just started, in start_period
• healthy — Health check is passing
• unhealthy — Health check is failing
• none — No health check configured

Managing Services

View Service Logs

Access real-time logs for any service through the UI or API:

# Via API
curl -X GET "http://localhost:8090/api/deployments/my-app/logs?service=web&tail=100" \
  -H "Authorization: Bearer $TOKEN"

View Service Stats

Monitor CPU, memory, and network usage:

# Via API
curl -X GET "http://localhost:8090/api/deployments/my-app/stats" \
  -H "Authorization: Bearer $TOKEN"

Stats include:

• CPU — Usage percentage
• Memory — Used, limit, and percentage
• Network — Bytes received and transmitted
• Block I/O — Read and write operations

Restart a Service

Restart a specific service without affecting others in the deployment:

# Restart via docker compose
docker compose -f /path/to/deployment/docker-compose.yml restart web

# Or restart the entire deployment via API
curl -X POST "http://localhost:8090/api/deployments/my-app/restart" \
  -H "Authorization: Bearer $TOKEN"

Container Operations

FlatRun provides direct container management outside of deployments:

List All Containers

curl -X GET "http://localhost:8090/api/containers" \
  -H "Authorization: Bearer $TOKEN"

Start/Stop/Restart Container

# Start
curl -X POST "http://localhost:8090/api/containers/{id}/start" \
  -H "Authorization: Bearer $TOKEN"

# Stop
curl -X POST "http://localhost:8090/api/containers/{id}/stop" \
  -H "Authorization: Bearer $TOKEN"

# Restart
curl -X POST "http://localhost:8090/api/containers/{id}/restart" \
  -H "Authorization: Bearer $TOKEN"

Remove Container

curl -X DELETE "http://localhost:8090/api/containers/{id}" \
  -H "Authorization: Bearer $TOKEN"

Networking Between Services

Services within the same deployment can communicate using their service names as hostnames. Docker's internal DNS resolves these names automatically.

services:
  app:
    image: myapp
    environment:
      # Reference the 'db' service by name
      DATABASE_HOST: db
      REDIS_HOST: cache

  db:
    image: postgres

  cache:
    image: redis

Scaling Services

Scale services by specifying the number of replicas:

services:
  worker:
    image: myapp-worker
    deploy:
      replicas: 3

Service settings

Each service can keep its own settings, set from its Settings tab or with PUT /api/projects/:name/services/:service/settings:

• Resources: a CPU limit such as 0.5 and a memory limit such as 512m (at least 6m)
• Restart policy: no, always, unless-stopped or on-failure
• Log rotation: the size of each log file and how many to keep
• Variables: merged over the compose file's own; values are taken literally
• Command and entrypoint: replace the image's own

FlatRun saves them in service.yml and writes them to docker-compose.flatrun.yml, a second compose file passed after the project's own. Your compose file is never rewritten, and a redeploy from Git keeps the settings. To run the project without FlatRun, pass both files:

docker compose -f docker-compose.yml -f docker-compose.flatrun.yml up -d

The running container keeps its old settings until the service is recreated, which the Settings tab offers after saving. Limits changed on a running container are saved the same way, unless the project requires plans or protects updates.

Sleeping one service

A single service can stop after it has been idle and start again on the next request, while the rest of the project keeps running. Turn it on from the service's Settings tab, or with PUT /api/projects/:name/services/:service/sleep and {"enabled": true, "idle_minutes": 15}. The idle time is at least 5 minutes.

• A service is busy while requests reach it, or while its containers receive more than 16 KiB of network traffic a minute. A service on a busy shared network may never count as idle.
• A service stays up while a running, awake service depends on it, so a database sleeps only after everything that uses it is asleep.
• A request to a sleeping service shows a short waking page. Its sleeping dependencies start first, then the service. Starting the service by hand does the same.
• Sleep for the whole project, set in its Deployments section, takes precedence. While it is on, per-service sleep is kept but not used.

Multi-Domain Support

A single deployment can serve multiple domains. Configure domains in the service.yml:

name: My App
domains:
  - id: primary
    service: web
    domain: example.com
    port: 80
    ssl:
      enabled: true
    aliases:
      - www.example.com
  - id: api
    service: api
    domain: api.example.com
    port: 8080
    path: /
    ssl:
      enabled: true
  - id: admin
    service: admin
    domain: admin.example.com
    port: 3000
    ssl:
      enabled: true

Multi-Database Support

Deployments can connect to multiple databases. Configure databases in the service.yml:

name: My App
databases:
  - id: primary
    alias: primary
    type: mysql
    mode: shared          # Use shared infrastructure database
    database: myapp_prod
    username: myapp_user
    env_prefix: DB_       # Creates DB_HOST, DB_PORT, etc.
    is_shared: true
  - id: analytics
    alias: analytics
    type: postgres
    mode: container       # Use database in this deployment
    service: postgres
    host: postgres
    port: 5432
    database: analytics
    env_prefix: ANALYTICS_DB_
  - id: cache
    alias: cache
    type: redis
    mode: external        # External database server
    host: redis.example.com
    port: 6379
    env_prefix: REDIS_

Database Modes

• shared — Uses the shared infrastructure database (MySQL/PostgreSQL)
• container — Uses a database container within the deployment
• external — Connects to an external database server