Services - FlatRun Docs

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:

Property	Description
`name`	Service name from docker-compose.yml
`container_id`	Docker container ID
`image`	Docker image being used
`status`	Current container state (running, stopped, etc.)
`health`	Health check status (healthy, unhealthy, none)
`ports`	Exposed port mappings
`networks`	Connected Docker networks

Container States

Containers can be in one of these states:

State	Description
`running`	Container is running normally
`created`	Container created but not started
`restarting`	Container is restarting
`paused`	Container is paused
`exited`	Container has stopped
`dead`	Container failed to stop properly

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

Note: When scaling services, ensure port mappings don't conflict. Use port ranges or let Docker assign ports automatically.