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

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