convox/docs/reference/app/primitives/service.md

Service

A Service is a horizontally-scalable collection of durable Processes.

Processes that belong to a Service are automatically restarted upon termination.

Services can be scaled to a static count or autoscaled in a range based on metrics.

Definition

A Service is defined in convox.yml.

services:
  web:
    port: 5000

---

services:
  web:
    agent: false
    build: .
    command: bin/web
    domain: ${WEB_HOST}
    drain: 10
    environment:
      - FOO
      - BAR=qux
    health:
      grace: 10
      interval: 5
      path: /check
      timeout: 3
    internal: false
    port: 5000
    ports:
      - 5001
      - 5002
    privileged: false
    scale:
      count: 1-3
      cpu: 128
      memory: 512
      targets:
        cpu: 50
        memory: 80
    singleton: false
    sticky: true
    test: make test
    volumes:
      - /shared

Attributes

Attribute	Type	Default	Description
agent	boolean	false	Set to true to declare this Service as an Agent
build	string/map	.	Build definition (see below)
command	string	CMD of Dockerfile	The command to run to start a Process for this Service
domain	string		A custom domain(s) (comma separated) to route to this Service
drain	number		The number of seconds to wait for connections to drain when terminating a Process of this Service
environment	list		A list of environment variables (with optional defaults) to populate from the Release environment
health	string/map	/	Health check definition (see below)
image	string		An external Docker image to use for this Service (supercedes build)
internal	boolean	false	Set to true to make this Service only accessible inside the Rack
port	string		The port that the default Rack balancer will use to route incoming traffic
ports	list		A list of ports available for internal service discovery or custom Balancers
privileged	boolean	true	Set to false to prevent Processes of this Service from running as root inside their container
scale	map	1	Horizontal scaling definition (see below)
singleton	boolean	false	Set to true to prevent extra Processes of this Service from being started during deployments
sticky	boolean	false	Set to true to enable sticky sessions
test	string		A command to run to test this Service when running convox test
volumes	list		A list of directories to share between Processes of this Service

Environment variables must be declared to be populated for a Service.

build

Specifying build as a string will set the path and leave the other values as defaults.

Attribute	Type	Default	Description
manifest	string	Dockerfile	The filename of the Dockerfile
path	string	.	The path (relative to convox.yml) to build for this Service

health

Specifying health as a string will set the path and leave the other values as defaults.

Attribute	Type	Default	Description
grace	number	5	The number of seconds to wait for a Process to start before starting health checks
interval	number	5	The number of seconds between health checks
path	string	/	The path to request for health checks
timeout	number	4	The number of seconds to wait for a successful response

scale

Specifying scale as a number will set the count and leave the other values as defaults.

Attribute	Type	Default	Description
count	number	1	The number of Processes to run for this Service. For autoscaling use a range, e.g. 1-5
cpu	number	128	The number of CPU units to reserve for Processes of this Service where 1024 units is a full CPU
memory	number	256	The number of MB of RAM to reserve for Processes of this Service
targets	map		Target metrics to trigger autoscaling

scale.targets

Attribute	Type	Default	Description
cpu	number		The percentage of CPU utilization to target for Processes of this Service
memory	number		The percentage of memory utilization to target for Processes of this Service

Command Line Interface

Listing Services

$ convox services -a myapp
SERVICE  DOMAIN                                PORTS
web      web.convox.0a1b2c3d4e5f.convox.cloud  443:5000

Scaling a Service

$ convox scale web --count 3 --cpu 256 --memory 1024 -a myapp
Scaling web... OK

Restarting a Service

$ convox services restart web -a myapp
Restarting web... OK

Restarting a Service will begin a rolling restart with graceful termination of each Process of the Service.