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:

LabelExampleDescription
shipyard.initpython manage.py 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", "some-script.sh"]'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", "some-script.sh"]'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:

LabelExampleDescription
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/poststart.sh"]'command to run on Kubernetes post-start event (as JSON string)
shipyard.lifecycle.preStop.exec.command'["sh", "/srv/prestop.sh"]'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'

services:

  web:
    labels:
      shipyard.route: '/'
      shipyard.init: 'python manage.py db upgrade'
      shipyard.route.rewrite: 'true'
      shipyard.cloudsql.sidecar: 'true'
    build:
      context: '.'
      dockerfile: 'docker/Dockerfile'
    env_file:
      - environments/local.env
    environment:
      DEV: ${DEV}
    entrypoint: '/entrypoints/web.sh'
    command: 'flask run'
    deploy:
      replicas: 2
    depends_on:
      - db
    ports:
      - 8080:8080  # the first container port listed is where HTTP requests are sent

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

volumes:
  db-data:
    labels:
      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.

Usage​

  • 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.

Output​

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'
services:
  http-echo:
    labels:
      shipyard.route: '/'
    image: jmalloc/echo-server
    ports:
      - '8080'

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

  cronjob:
    labels:
      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"'