Skip to main content

Define via Compose

Shipyard parses all the data it needs from Compose services and volumes.

Shipyard-specific functionality is specified via labels, so the first step of deploying your application on Shipyard is adding the necessary labels to your compose file.

Supported service labels

All Environments

The following labels are available on all environments (Shipyard-hosted or user-hosted), unless specified:

shipyard.initpython db migratecommand to run before your service starts
shipyard.init.init-containertrueconfigures the shipyard.init command to run in an init container
shipyard.jobtruerun this service as a Job
shipyard.job.schedule'*/2 * * * *'run this service as a scheduled CronJob
shipyard.job.*specify additional Kubernetes job labels - see Jobs
shipyard.liveness.exec.command'["bash", ""]'The command to be executed, formatted as a JSON array
shipyard.liveness.failure_threshold1# of probe attempts before the container is restarted
shipyard.liveness.http.headers'{"x-reason": "health"}'JSON string of headers to include with your probes
shipyard.liveness.http.path/healthzthe GET path the probe should hit
shipyard.liveness.initial_delay10# of seconds to wait before starting probes
shipyard.liveness.period15# of seconds between your probes
shipyard.liveness.timeout_seconds10# of seconds after which the probe times out
shipyard.primary-routetrueif enabled, this service's URL will be the primary URL for the environment (useful for multi-domain environments)
shipyard.readiness.exec.command'["bash", ""]'The command to be executed, formatted as a JSON array
shipyard.readiness.failure_threshold1# of probe attempts before the container is considered Unready and stops receiving traffic
shipyard.readiness.http.headers'{"x-reason": "health"}'JSON string of headers to include with your probes
shipyard.readiness.http.path/healthzthe GET path the probe should hit
shipyard.readiness.initial_delay10# of seconds to wait before starting probes
shipyard.readiness.period15# of seconds between your probes
shipyard.readiness.success_threshold1# of consecutive successes for the probe to be considered successful after having failed
shipyard.readiness.timeout_seconds10# of seconds after which the probe times out
shipyard.route/send HTTP requests with this prefix to this service's first defined container port
shipyard.route.*/apispecify any # of named routes
shipyard.route.oauth.redirect-uri1/callback/oauth/githubcallback path the Callback Gateway should send requests to
shipyard.route.oauth.*.redirect-uri1/callback/oauth/googlespecify any # of callback paths for Callback Gateway
shipyard.route.rewrite1trueif enabled, prepend the shipyard.route path prefix to requests that don't have it

1 Not supported on Launch Environments

Launch Environments (User-cloud Environments)

The following labels are only available when deploying environments to a user's cloud:

shipyard.cloudsql.sidecartrueif enabled, start this container with a GCP CloudSQL sidecar
shipyard.deploy.disk.size10Giallocate a disk of the specified size to serve as this volume
shipyard.lifecycle.postStart.exec.command'["sh", "/srv/"]'command to run on Kubernetes post-start event (as JSON string)
shipyard.lifecycle.preStop.exec.command'["sh", "/srv/"]'command to run on Kubernetes pre-stop event (as JSON string)
shipyard.securityContext'{"capabilities": {"add": ["SYS_ADMIN"]}}'direct definition of Kubernetes security context (as JSON string)

Example Compose file

Here's an example of a Compose file for a Flask and Postgres application, ready to be deployed with Shipyard:

version: '3'


shipyard.route: '/'
shipyard.init: 'python db upgrade'
shipyard.route.rewrite: 'true'
shipyard.cloudsql.sidecar: 'true'
context: '.'
dockerfile: 'docker/Dockerfile'
- environments/local.env
entrypoint: '/entrypoints/'
command: 'flask run'
replicas: 2
- db
- 8080:8080 # the first container port listed is where HTTP requests are sent

image: 'postgres:9.6-alpine'
PGDATA: '/var/lib/postgresql/data/pgdata'
- 'db-data:/var/lib/postgresql/data/pgdata'
- 5432:5432

shipyard.deploy.disk.size: 10Gi

Supported service properties

Each of the following Compose service properties is supported:

  • build.context
  • build.dockerfile
  • command
  • container_name
  • depends_on
  • deploy.replicas
  • entrypoint
  • env_file
  • environment
  • expose
  • image
  • labels
  • ports
  • volumes
  • working_dir

Jobs & CronJobs

Using the labels shipyard.job.*, you can specify Compose services as Jobs or CronJobs.


  • A service with the label shipyard.job: true (and no shipyard.job.schedule) will be a single-run Job.
  • A service with the label shipyard.job: true and shipyard.job.schedule: [crontab] will be a CronJob.

The other labels shown in the example below map 1:1 with the Kubernetes Job properties of the same name.


Like a normal environment build, you can see the output of a Job on the Build Details page under the Run Logs tab. You can also view them on the Web Terminal: previous runs are listed as Completed Jobs.

Example Compose file

This example file creates three Shipyard services. The first is a basic service with a route. The second will run once when the environment starts up. The third will run every two minutes.

version: '3'
shipyard.route: '/'
image: jmalloc/echo-server
- '8080'

shipyard.job: true
image: busybox
command: 'echo "Hello and Goodbye World"'

shipyard.job: true
shipyard.job.schedule: '*/2 * * * *'
shipyard.job.restartPolicy: Never
shipyard.job.backoffLimit: 2
shipyard.job.activeDeadlineSeconds: 60
shipyard.job.successfulJobsHistoryLimit: 5
shipyard.job.failedJobsHistoryLimit: 3
shipyard.job.concurrencyPolicy: Forbid
image: busybox
command: 'echo "Hello World"'