Skip to content

deploy.yaml ​

deploy.yaml describes one application: its image, or the Dockerfile to build one from, or the folder to serve, how to run it, the hostnames and the path it is served at, what the proxy does for it, and when its volumes are backed up. This page lists every field with its type, default and validation rules, the units used for sizes and durations, how ${NAME} placeholders are filled in, the error format that shipwick and the API produce, and shipwick.yaml, which describes several applications in one file.

The file ​

yaml
name: my-api
image: ghcr.io/company/my-api:1.4.2
port: 8080
domain: api.example.com
replicas: 2
  • Only name and image are required, or build in place of image. A folder the proxy serves itself needs name, static and domain, and nothing that describes a container applies.
  • The file is YAML. JSON is accepted too, since it is a subset of YAML.
  • One file describes one application. A file with several YAML documents is rejected. Several applications go in one shipwick.yaml instead.
  • The maximum size is 64 KB.
  • Unknown fields are errors. A misspelled key is reported, not ignored.
  • shipwick looks for deploy.yaml in the current directory, then for shipwick.yaml; -f / --file selects another file, and can be repeated to deploy several applications in order. shipwick init writes a starter file, with a Dockerfile for a project it recognises, and shipwick validate checks a file offline and prints it as it will be applied, defaults included.

The same parser and validator run in shipwick and in the agent. The agent validates every submitted document again, whatever the client did.

Placeholders ​

A value may refer to something the file must not contain, such as a password, as ${NAME}:

yaml
env:
  DATABASE_URL: postgres://app:${DATABASE_PASSWORD}@postgres:5432/app

Two places can fill it in. shipwick replaces every ${NAME} it has a value for before the file is validated or sent, from its own environment or from a file given with --env-file. An env value, or a password under proxy.basic_auth, whose name is set nowhere there is left to the agent, which fills it in from the secrets stored on the server with shipwick secret set NAME, before the deployment is recorded; the record holds the values, so a later change of a secret applies from the next deployment on and a rollback restores the value that deployment used. A name that neither side has is an error, never an empty value, and the deployment is refused before anything is recorded, with the command to run. Only env values and the passwords of proxy.basic_auth are filled in by the server: a ${TAG} in image must be set where shipwick runs. $${NAME} is a literal ${NAME}. The rules are in the CLI reference.

Fields ​

FieldTypeRequiredDefault
namestringyes
imagestringunless build or static is set
build., a folder, or {context, dockerfile}in place of image
build.contextstringno., the directory of deploy.yaml
build.dockerfilestringnoDockerfile
statica folder, or {dir, fallback}in place of image; requires domain
static.dirstringwith static as a map
static.fallbackstringnonone: a path that names no file is a 404
entrypointlist of strings, or one stringnothe image's ENTRYPOINT
commandlist of strings, or one stringnothe image's CMD
userstringnothe image's USER
portintegerwith domain or health.pathnone
domainstringnonone
aliaseslist of stringsnonone
redirectslist of stringsnonone
pathstringno; requires domainthe whole domain
proxy.strip_prefixbooleanno; requires pathfalse
proxy.headersmap of string to stringnonone
proxy.basic_auth[].pathstringnothe whole application
proxy.basic_auth[].usernamestringwith proxy.basic_auth
proxy.basic_auth[].passwordstringwith proxy.basic_auth
proxy.redirects[].fromstringwith proxy.redirects
proxy.redirects[].tostringwith proxy.redirects
proxy.redirects[].statusintegerno308
replicasintegerno1
envmap of string to stringnonone
health.pathstringone of path, tcp, command with health
health.tcpintegerone of path, tcp, command with health
health.commandlist of stringsone of path, tcp, command with health
health.intervaldurationno10s
health.timeoutdurationno3s
health.retriesintegerno3
health.start_perioddurationno0s
resources.cpunumbernounlimited
resources.memorysizenounlimited
volumes[].namestringwith volumes
volumes[].pathstringwith volumes
backups.schedulestringwith backups; requires volumes
backups.keepintegerno7
backups.beforelist of stringsnonone
backups.before_timeoutdurationno; requires backups.before1h
backups.before_instringno; requires backups.beforereplica
backups.stopbooleannofalse
publish[].portintegerwith publish
publish[].hostintegernothe same as port
publish[].addressstringnoevery address of the server
publish[].protocolstringnotcp
logging.driverstringwith logging
logging.optionsmap of string to stringnonone
pre_deploy.commandlist of stringswith pre_deploy
pre_deploy.timeoutdurationno10m
jobs[].namestringwith jobs
jobs[].schedulestringwith jobs
jobs[].commandlist of stringswith jobs
jobs[].timeoutdurationno1h
restart.policystringnoalways
deploy.strategystringnorolling
deploy.stop_timeoutdurationno10s
initbooleannofalse
security.read_onlybooleannofalse
security.tmpfs[]list of paths, or of {path, size}no
security.capabilitiesnone, or a list of stringsnoDocker's default set
security.non_rootbooleannofalse
afterlist of stringsno; shipwick.yaml only

With static, only name, static, domain, aliases, redirects, path and proxy apply; a field that describes a container is an error next to it.

name ​

Identifies the application on the server. It appears in container names, Docker labels, API URLs and the proxy configuration, and it is the hostname under which other applications on the server reach this one, so the alphabet is deliberately strict.

Typestring
Requiredyes
RuleA DNS label: lowercase letters, digits and dashes; must start and end with a letter or digit; 1 to 63 characters. Pattern: ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
Reservedagent, caddy, dashboard and localhost cannot be application names. They belong to Shipwick's own containers on the network the applications share.
yaml
name: my-api

Underscores are not allowed. Container names have the form shipwick_<name>_<deployment>_<replica> and rely on that.

Other applications on the server reach this one at http://<name>:<port>, where port is the one in this file. See Call one application from another.

When deploying through the API, the name in the document must match the name in the URL.

image ​

The image to run. Any image reference Docker understands. Instead of naming an image, build builds one on your machine, and static serves a folder with no image at all.

Typestring
Requiredyes, unless build or static is set. Next to build, an image is an error: is built here; remove image or build.
RuleA well-formed image reference without whitespace. Leading and trailing whitespace is trimmed.
yaml
image: ghcr.io/company/my-api:1.4.2

The deployment's version is derived from the reference:

ReferenceVersion
With a tag: ghcr.io/company/my-api:1.4.2The tag: 1.4.2
With a digest only: my-api@sha256:4f2a…sha256: and the first 12 hex characters of the digest
With neither: nginxlatest

Pin a version tag. Deployments are recorded, and rolled back, by it.

shipwick deploy --image <ref> replaces this field for one deployment without changing the file. For private registries, see Pull from private registries.

build ​

Build the image on your machine instead of naming one. shipwick deploy runs docker build where it runs, for the server's architecture, tags the result shipwick.local/<name>:<UTC timestamp>-<4 hex>, sends the archive to the agent and deploys it like any other image. No registry is involved, and the server never builds; Docker must be installed where shipwick deploy runs. See Images built where you are.

TypeA string, the build context; or a map with context and dockerfile
Requiredno. Replaces image; cannot be combined with static.
build.contextDefault .. The directory handed to docker build, relative to deploy.yaml: . for its own directory, or a folder in it such as api.
build.dockerfileDefault Dockerfile. Relative to the context.
RuleBoth paths are relative and contain no control characters. The context stays inside the directory of deploy.yaml: must be relative to deploy.yaml, must stay inside the directory of deploy.yaml; the Dockerfile stays inside the context: must be relative to the context, must stay inside the context (since 0.10 the messages say so; before, both said deploy.yaml, though the Dockerfile was relative to the context all along). Backslashes are read as slashes; paths are cleaned.
Unknown keysSince 0.10 a key the block does not know is an error with its line, line 5: / unknown field "dockerfil", as in every other block; before, it was dropped without a word and the default Dockerfile built.
yaml
build: .
yaml
build:
  context: .
  dockerfile: docker/Dockerfile.prod

A map that names only its Dockerfile, build: {dockerfile: docker/Dockerfile.prod}, builds in the directory of deploy.yaml.

The deployment's version is the image tag, 20260927-153000-a1b2; every deployment is a new build. shipwick validate describes the build and does not run it; shipwick deploy --image does not apply to an application with build. shipwick.local is a host that does not exist, so such an image is either on the server or it is not: a rollback to a version whose image was pruned, or that this server was never sent, fails and asks for another shipwick deploy from the project. shipwick init writes build: . together with a Dockerfile for a project it recognises.

static ​

A folder served by the proxy as it is: a built frontend. There is no container, so nothing that describes one applies. shipwick deploy uploads the folder, up to 512 MB, and the agent copies it into the proxy and routes the domain to it. See A folder instead of a container.

TypeA string, the folder; or a map with dir and fallback
Requiredno. Replaces image. Requires domain: is required for a static application: the proxy serves the files at it.
static.dirRequired as a map. A folder relative to deploy.yaml, inside its directory: dist/, build, out/public. Read on the machine where shipwick deploy runs, at deploy time. Backslashes are read as slashes; trailing slashes are dropped.
static.fallbackA file in the folder, answered with status 200 for every path that names no file: index.html for a single-page application. Relative to the folder, at most 200 characters, with letters, digits, dots, dashes, underscores and tildes between the slashes. Without it such a path is a 404.
Excludesimage, build, port, replicas, env, health, resources, volumes, publish, entrypoint, command, user, logging, pre_deploy, jobs, backups, deploy.stop_timeout, init and security. Each is refused with does not apply to a static application: the proxy serves the files, there is no container.
yaml
name: web
static: dist/
domain: example.com
redirects: [www.example.com]
yaml
static:
  dir: dist/
  fallback: index.html

Run the build first: the folder is sent as it is. It must hold an index.html, which shipwick deploy checks before anything is sent and the agent checks again. A request for a path that names no file is a 404 unless fallback names the page that answers it; a missing image or script then gets that page too. The fallback file must be in the folder, which shipwick deploy checks before it uploads and the agent before it routes. Files and directories only; a symbolic link that leads out of the folder is skipped with a warning. deploy.yaml, shipwick.yaml, .git and .env files are left out wherever they are in the folder, since everything sent is served; other dotfiles such as .well-known go in. The version of a static deployment is the first twelve characters of the folder's digest, so the same files make the same version on any machine. aliases, redirects, path, proxy, stop (the domain answers 503), start, rollback and delete work as for any application; shipwick logs, run, jobs and the metrics have nothing to show and say so. shipwick init writes static: <dir> for a folder of static files and for an Astro project that builds one, and static: {dir: dist/, fallback: index.html} for a project built by Vite.

entrypoint ​

Replaces the image's ENTRYPOINT, the way docker run --entrypoint does. Omit it to keep the image's own.

Typelist of strings, or one string
Requiredno
Defaultthe image's ENTRYPOINT
Rule1 to 64 arguments. No argument contains a newline, a carriage return or a NUL byte. An empty list is an error: omit the field instead.
yaml
entrypoint: ["dotnet"]

The arguments reach the container exactly as written. A string is one argument, spaces included: there is no shell in between, so entrypoint: dotnet App.dll starts a program called dotnet App.dll. Use a list for several arguments. A value that is neither a string nor a list of strings is a syntax error, reported with its line number.

Whatever runs, runs inside the container, as the image's own command would. Nothing in deploy.yaml runs on the server.

command ​

Replaces the image's CMD, the way the arguments after the image do in docker run. Same type and rules as entrypoint.

Typelist of strings, or one string
Requiredno
Defaultthe image's CMD
Rule1 to 64 arguments. No argument contains a newline, a carriage return or a NUL byte. An empty list is an error: omit the field instead.
yaml
image: ghcr.io/company/my-api:1.4.2
command: ["node", "worker.js"]

The usual reason: a worker, or a second program, from the same image as the API. As a string, command: node worker.js would start a program called node worker.js.

user ​

The user the process runs as, replacing the image's USER, like docker run --user.

Typestring
Requiredno
Defaultthe image's USER
RuleA user name or a numeric id, alone or as user:group. A name is a lowercase letter or underscore followed by up to 31 lowercase letters, digits, underscores or dashes; an id is 1 to 10 digits. Pattern: ^([a-z_][a-z0-9_-]{0,31}|[0-9]{1,10})(:([a-z_][a-z0-9_-]{0,31}|[0-9]{1,10}))?$
NormalizationLeading and trailing whitespace is trimmed.
yaml
user: "1000:1000"

app, 1000, 1000:1000, 1000:app and app:app are all valid. A bare number, user: 1000, is read as the id 1000. A name is resolved by the container's own /etc/passwd, so it has to exist in the image.

port ​

The port the application listens on inside the container. The reverse proxy, an HTTP health check and the other applications on the server reach it over the private networks. It is not published on the server unless publish lists it.

Typeinteger
Requiredwhen domain or health.path is set
Rule1 to 65535
yaml
port: 8080

A tcp health check names its own port and a command check needs none, so neither requires this field.

An application without a port gets no name on the services network, so other applications cannot call it.

domain ​

The public hostname of the application. Caddy serves it over HTTPS with an automatically obtained certificate. See Routing and HTTPS.

Typestring
Requiredno. Requires port.
RuleA hostname: dot-separated labels of lowercase letters, digits and dashes, each 1 to 63 characters and starting and ending with a letter or digit; at most 253 characters in total. No scheme, port or path. The first label may be *, a wildcard: "*.example.com".
NormalizationTrimmed and converted to lowercase.
yaml
domain: api.example.com

More hostnames are added with aliases, served exactly like the domain, and redirects, answered with a redirect to it. path limits the application to one path of its hostnames.

Wildcards. domain and aliases may be a wildcard: one leading * label and a plain hostname after it, quoted in YAML.

yaml
domain: example.com
aliases: ["*.example.com"]

*.example.com is every name one label below the domain: a.example.com, and neither example.com nor a.b.example.com. A certificate for a wildcard is issued only through a DNS record, so the agent refuses a deployment that names one unless it has SHIPWICK_CLOUDFLARE_API_TOKEN or a certificate of your own covers the name: see Cloudflare in front of the server and a certificate of your own. *.example.com and api.example.com are different hostnames and may belong to different applications; a request for api.example.com goes to the application that names it exactly, every other name under the domain to the wildcard's. redirects cannot be wildcards, and cannot be sent to a wildcard domain.

Hostnames in use. A hostname that is served, as a domain or an alias, is taken per path: two applications may name the same hostname when each serves a different path of it, and the same path twice, or none on both, is refused. A hostname that is redirected, or that the agent's API or the dashboard is served at, is taken whole. A deployment that claims what is already in use is refused before anything is started. The error is shaped like a validation error, and its field names the line to change: domain, path, aliases[0], redirects[1]. Its message names the owner: already served by application "web", or already served by Shipwick itself (the agent or the dashboard); for an application with a path, example.com/api is already served by application "api"; applications share a domain under different paths. A redeploy or a rollback is checked the same way, since a stored configuration's hostnames may have been taken since.

An application that is only called by other applications on the server needs no domain.

aliases ​

More hostnames served exactly like domain: the same route, the same replicas, the same path. Each gets its own certificate; point each one's DNS at the server. See Serve several hostnames and redirect www.

Typelist of strings
Requiredno. Requires domain.
RuleAt most 20 entries. Each is a hostname by the same rule as domain, wildcards included, and is listed once across domain, aliases and redirects.
NormalizationEach entry is trimmed and converted to lowercase. The order is kept.
yaml
domain: example.com
aliases: [api.example.com]

Without a domain, aliases is an error: an alias is served like the domain, so there has to be one. A hostname that appears twice, in whichever lists, is reported on its second occurrence: "example.com" is already listed under domain, "a.example.com" is already listed under aliases[0].

Like the domain, an alias in use by another application under the same path, or by Shipwick itself, is refused by the agent, with an error on aliases[i].

redirects ​

Hostnames answered with a 308 redirect to https://<domain>, with the same path and query; the method is kept. For an application with a path, the redirect leads to https://<domain><path>, followed by the request's path and query. For www.example.com and old domains. Redirects from one path to another are proxy.redirects.

Typelist of strings
Requiredno. Requires domain, and one that is not a wildcard: cannot be sent to a wildcard domain.
RuleAt most 20 entries. Each is a plain hostname, never a wildcard, and is listed once across domain, aliases and redirects.
NormalizationEach entry is trimmed and converted to lowercase. The order is kept.
yaml
domain: example.com
redirects: [www.example.com, example.net]

https://www.example.com/docs?x=1 is answered with a 308 to https://example.com/docs?x=1. A redirect needs no replica: it is answered whether or not the application is running, including while it is stopped. Every redirected hostname gets its own certificate, so its DNS must point at the server.

Since 0.6 a redirect leads below the application's path when it has one. With domain: example.com, path: /api and redirects: [api.example.net], https://api.example.net/users?page=2 is answered with a 308 to https://example.com/api/users?page=2. Before, it led to the same path on the domain, which may belong to another application.

Without a domain, redirects is an error: a redirect is sent to the domain. A redirect is a whole hostname, whatever the application's path, so it cannot be shared: a hostname in use anywhere is refused, with an error on redirects[i].

path ​

Limits the application to one path of its domain and everything under it, so that several applications answer under one hostname. See Several applications on one hostname.

Typestring
Requiredno. Requires domain.
Defaultthe whole domain. path: / means the same.
RuleStarts with / and does not end with one; letters, digits, dots, dashes, underscores and tildes between the slashes; no . or .. segments; at most 200 characters. Pattern: ^(/[A-Za-z0-9._~-]+)+$
NormalizationLeading and trailing whitespace is trimmed.
yaml
name: api                 # example.com/api and everything under it
domain: example.com
path: /api
yaml
name: web                 # the rest of example.com
domain: example.com

The longest path wins: with a third application at /api/admin, a request for /api/admin/users goes there, /api/users to api, and everything else to web. Without an application that takes the rest, the rest is a 404. A path matches whole segments, /api and /api/users but not /apix, and without regard to case, so /API and /api are one path. Each application keeps its own replicas, health checks, rollouts and rollbacks. Aliases are served under the same path; redirects remain whole hostnames, and lead to the application's path: see redirects.

Two applications cannot have the same path of a hostname, or both none: the second deployment is refused by the agent with an error on path, as described under domain.

The application sees the path as the visitor sent it, /api/users, unless proxy.strip_prefix removes the prefix. A static application under a path is always served with the prefix removed, since its files are looked up in its folder, and a request for the path itself is sent on with a trailing slash, so that relative links in the page lead below it.

proxy ​

What the proxy does for the application's requests besides passing them on: response headers, basic authentication, redirects from one path to another, and removing path before the application sees a request. See Several applications on one hostname for each of them at work.

FieldTypeDefaultRule
proxy.strip_prefixbooleanfalseRequires path. Removes it from a request before the application sees it: /api/users arrives as /users.
proxy.headersmap of string to stringnoneAt most 50 headers. A name is an HTTP token, letters, digits and dashes in practice, and is listed once whatever its case. A value is not empty, at most 4096 characters, and contains no control characters or newlines. Headers that belong to the connection are refused: Connection, Content-Encoding, Content-Length, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection, TE, Trailer, Transfer-Encoding, Upgrade.
proxy.basic_auth[].pathstringthe whole applicationA path by the same rule as path, inside the application's own path when it has one. / means the whole application.
proxy.basic_auth[].usernamestringrequiredAt most 255 characters; no colon, no control characters and, since 0.10, no braces, which the proxy would read as a placeholder. Listed once for each path.
proxy.basic_auth[].passwordstringrequiredAt least 8 characters and at most 72 bytes; no control characters. A secret: write it as a placeholder.
proxy.redirects[].fromstringrequiredOne path, matched exactly, by the same rule as path and inside the application's own path. Not /. Listed once.
proxy.redirects[].tostringrequiredA path on the same host, starting with one /, with or without a query; or an absolute https:// URL. At most 2048 characters; no whitespace, control characters, braces or backslashes.
proxy.redirects[].statusinteger308One of 301, 302, 307, 308.

At most 20 basic_auth entries and 100 redirects. The block requires domain, and an unknown key inside it is an error like anywhere else in the file.

yaml
domain: example.com
path: /api
proxy:
  strip_prefix: true              # the application sees /users for /api/users
  headers:                        # set on every response
    X-Frame-Options: DENY
    Strict-Transport-Security: max-age=31536000
  basic_auth:
    - path: /api/admin            # optional; without it, the whole application
      username: admin
      password: ${ADMIN_PASSWORD}
  redirects:
    - from: /api/old
      to: /api/new                # or an https:// URL
      status: 308                 # 301, 302, 307 or 308

A request meets them in this order: a redirect answers first, then the proxy asks for a password, then the application, or the folder of a static one, answers, and the headers are set on what it sends, replacing a header of the same name. The headers are on the redirects too, and not on the 401 that asks for the password.

Every path in the block is the path as the visitor asks for it: under path: /api, the admin area is /api/admin, with or without strip_prefix, and a path outside /api is refused.

  • strip_prefix. The proxy does not rewrite responses: an application that is served without its prefix must add it to its own redirects and links.
  • headers. Values are sent as written; nothing in them is expanded by the proxy.
  • basic_auth. A password is a secret, treated like an env value: ${ADMIN_PASSWORD} is filled in by shipwick from its environment or --env-file, else by the agent from the secrets stored with shipwick secret set. It is encrypted in the agent's database, shown as ******** wherever the configuration is shown, and the proxy is given a bcrypt hash of it, never the password. Several entries with the same path are several users of it. Where the paths of two entries overlap, the longer one decides: with one account for everything and another for /admin, /admin accepts only the second. A password left to the server's secrets is checked by the agent once its value is known.
  • redirects. The query string travels along unless to has one. The default status, 308, keeps the method. A redirect to itself, or a circle of them, is refused.

replicas ​

The number of identical containers to run.

Typeinteger
Default1
Rule1 to 50. Must be 1 when volumes or publish is set.
yaml
replicas: 2

Replicas cannot share a volume, and cannot share a server port. With both volumes and publish in the file, the volume rule is the one reported.

env ​

Environment variables passed to every replica, and to the pre_deploy command, the jobs and shipwick run.

Typemap of string to string
Defaultnone
Key ruleLetters, digits and underscores, not starting with a digit. Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
Value ruleMust not contain NUL bytes.
yaml
env:
  DATABASE_URL: postgres://app:${DATABASE_PASSWORD}@postgres:5432/app
  LOG_LEVEL: info

Values are stored on the server with the deployment. They are never logged and never echoed in validation errors. In every API response they are masked as ********; the names are kept. Since 0.7 the mask is refused as a value: "********" cannot be an env value or a basic-auth password, so a configuration copied out of an answer cannot be deployed with it. shipwick config gives the file back with a value that referred to a stored secret as that ${NAME} again, and every other value as the mask.

A value that must not be in the file is written as a placeholder, ${DATABASE_PASSWORD} above, and filled in by shipwick when you deploy.

Values are encrypted at rest

Environment values are encrypted with AES-256-GCM before they are written to the agent's database; the variable names, and everything else in the record, stay readable. The key is encryption.key in the agent's data directory, or SHIPWICK_ENCRYPTION_KEY. Back the key up together with the database: without it the database cannot be read. Encryption protects a copy of the database file, not the values inside a running container, which anyone with the Docker socket can read. See Security and Agent configuration.

health ​

The health check run against every replica. A check is one of three kinds, and exactly one of path, tcp and command is set; interval, timeout and retries mean the same for each. See Health checks and supervision.

FieldTypeRuleHealthy when
health.pathstringStarts with /; at most 2048 characters; no whitespace or control characters; a valid URL path without scheme or host. Requires port.GET <path> on port answers with a 2xx status. Redirects are not followed and do not count.
health.tcpintegerA container port, 1 to 65535. port is not needed.A TCP connection to that port is accepted.
health.commandlist of strings1 to 64 arguments, none empty, none containing a NUL byte. A list, not a string. The program has to exist in the image. port is not needed.The command, run inside the replica, exits with code 0.
FieldTypeDefaultRule
health.intervalduration10s1s to 5m
health.timeoutduration3s100ms to 1m
health.retriesinteger31 to 100
health.start_periodduration0sUp to 30m. Extra time a replica gets to come up before failed checks count, on top of interval × retries; during a deployment, and after a restart by the supervisor.
yaml
port: 8080
health:
  path: /health
  interval: 10s
  timeout: 3s
  retries: 3
yaml
health:
  tcp: 5432
yaml
health:
  command: ["pg_isready", "-U", "postgres"]

path is for anything that speaks HTTP. tcp says that the process is listening, which for a queue or a cache is usually all there is to know. command asks the application itself; a database can be listening and still refuse connections while it recovers. The command is run as given, without a shell.

The fields are used twice:

  • Deploying. A new replica has start_period + interval × retries (30 seconds with the defaults) to pass once, and is probed every second meanwhile. If it never does, the deployment fails and says why: GET /health on port 8080: connection refused, or for a command, its exit code and the last line it printed: command exited 2: pg_isready: no response. For a slow starter, a JVM or an application that migrates its database on boot, set start_period: 1m rather than raising retries, which would also make a running replica's failures take longer to notice.
  • Running. Every replica is probed every interval. A replica that fails retries probes in a row is marked unhealthy, taken out of rotation and restarted, unless restart.policy is never. A restarted replica gets start_period + interval × retries to come up again.

Without a health block, a deployment only verifies that new replicas are still running after 3 seconds.

A health block that names none of the three kinds, or more than one, is an error on health: one of path, tcp or command is required; path and tcp are set; a health check is one of path, tcp or command.

resources ​

Limits per replica. Omit a field, or the whole block, for unlimited. See Resource limits and metrics.

FieldTypeDefaultRule
resources.cpunumberunlimitedCores, as a decimal number. 0.01 to 512.
resources.memorysizeunlimitedA number and a unit, see Sizes. Minimum 6mb.
yaml
resources:
  cpu: 0.5
  memory: 512mb

Memory is a hard cap: swap does not extend it, and a container exceeding it is killed. The same limits apply to the pre_deploy command and to job containers.

volumes ​

Named Docker volumes mounted into the replica, for data that must outlive deployments: a database, above all. See Run a database or other stateful application.

FieldTypeRule
volumes[].namestringRequired. Same rule as name: lowercase letters, digits and dashes, starting and ending with a letter or digit, 1 to 63 characters. Unique within the file.
volumes[].pathstringRequired. An absolute, clean path inside the container: starts with /, is not / itself, contains no . or .. segments, no doubled or trailing slashes, and no NUL, CR or LF. Leading and trailing whitespace is trimmed. Unique within the file.

At most 10 volumes per application. volumes requires deploy.strategy: recreate and replicas: 1.

yaml
name: postgres
image: postgres:17
port: 5432
replicas: 1
env:
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
  - name: data
    path: /var/lib/postgresql/data
deploy:
  strategy: recreate

On the server the volume is the Docker volume shipwick_<name>_<volume>: shipwick_postgres_data here. It belongs to the application, not to a deployment: every deployment mounts the same volumes, and nothing removes them — not a redeploy, not a rollback, not shipwick delete. shipwick volumes lists every volume on the server with the application it belongs to and whether that application still exists; shipwick volumes rm shipwick_postgres_data removes one whose application was deleted, and refuses one whose application still exists. shipwick backup and shipwick restore copy a volume's contents out and back in, and backups has the server archive the volumes on a schedule; see Back up and restore volumes.

Volumes are named volumes only. A path on the host cannot be mounted. The pre_deploy command and job containers get no volumes: a replica may be writing them.

Two versions writing the same files at once is how data gets lost, which is why the strategy and the replica count are checked:

text
invalid deploy.yaml

deploy.strategy:
  must be "recreate" for an application with volumes: two versions cannot write the same files at once
  expected: deploy:
    strategy: recreate

replicas:
  must be 1 for an application with volumes, got 2: replicas cannot share a volume
  expected: 1

backups ​

Backups of the application's volumes, taken by the agent on a schedule. A backup is one tar archive per volume, kept on the server and, when the agent has a bucket, in S3-compatible storage as well. See Back up and restore volumes, and Agent configuration for where backups go and how they are encrypted.

FieldTypeDefaultRule
backups.schedulestringrequired when backups is presentFive cron fields, read in UTC, as for jobs. Runs of whitespace between fields are collapsed to one space.
backups.keepinteger71 to 365. How many successful backups are kept; the oldest go once a new one has succeeded.
backups.beforelist of stringsnoneA command run inside the running replica before the archive is taken. Same rule as pre_deploy.command: 1 to 256 arguments, the first not blank, none containing a NUL byte or longer than 4096 bytes. A list, not a string.
backups.before_timeoutduration1h1s to 24h. How long before may run. Requires backups.before. Since 0.6.
backups.before_instringreplicareplica or container: where before runs. Requires backups.before. Since 0.7.
backups.stopbooleanfalseStop the application while the archive is taken, and start it again whatever happens.

backups requires volumes: a backup is an archive of them. An unknown key inside the block is an error.

yaml
name: postgres
image: postgres:17
volumes:
  - name: data
    path: /var/lib/postgresql/data
deploy:
  strategy: recreate
backups:
  schedule: "0 3 * * *"     # five cron fields, UTC, like jobs
  keep: 7                   # successful backups kept; default 7
  before: ["pg_dump", "-U", "postgres", "-f", "/var/lib/postgresql/data/backup.sql", "app"]
  before_timeout: 1h        # how long `before` may run; default 1h, up to 24h
  before_in: replica        # where `before` runs: replica (default) or container
  stop: false               # stop the application for the archive; default false

Two things decide whether what is in the archive can be trusted:

  • before runs inside the running replica first, as a list of arguments, never through a shell: a dump written into the volume, a checkpoint. If it exits non-zero the backup fails and nothing is archived. It has an hour, or what before_timeout says, up to 24 hours; the application is held for as long as it runs. A command still running at the limit fails the backup the same way, with an error that names the key: backups.before did not finish within 1h; the backup was given up and nothing was archived. Give the command longer with backups.before_timeout in deploy.yaml (up to 24h). Docker has no way to end a command once it was started in a container, so one that hangs stays there until it ends by itself or the application is deployed or restarted; the backup no longer waits for it. before_in: container runs it where it can be ended.
  • stop: true stops the application for as long as the archive takes and starts it again whatever happens, a failed backup included. The application is down meanwhile.

Both may be given: the command runs, then the application stops. Without either, the archive is taken from under the running process, which is fine for uploads and not for a database.

before_in (since 0.7) says where before runs.

Value
replicaThe default. Inside the running replica, where a command that passes its limit stays until it ends by itself.
containerIn a container of its own beside the replica, for as long as the command takes. At before_timeout it is stopped — SIGTERM, and SIGKILL if it is still there ten seconds later — and removed, and the backup fails with backups.before did not finish within 1h and was stopped; nothing was archived. Give the command longer with backups.before_timeout in deploy.yaml (up to 24h). The same happens when the agent is stopped while it runs. The replica is not touched.

The container has the replica's image, env values, user and resources limits, the limits being its own; the volumes at the same paths; and the replica's network, so localhost and 127.0.0.1 are the replica on every port it listens on. It does not have the rest of the replica's filesystem — it starts from the image, so a socket the application keeps under /var/run or /tmp cannot be reached — nor the replica's processes, and the image's entrypoint is not run. A command that looks for a socket by default must be told a host: pg_dump and psql need -h localhost, mysqldump and mysql -h 127.0.0.1. See A before that is ended at its limit.

yaml
backups:
  schedule: "0 3 * * *"
  before: ["pg_dump", "-U", "postgres", "-h", "localhost", "-f", "/var/lib/postgresql/data/backup.sql", "app"]
  before_timeout: 30m
  before_in: container

Only successful backups count towards keep. A scheduled backup that fails is posted to the webhook as backup.failed. shipwick backups <app> lists the backups the server keeps, and shipwick backups run <app> takes one now, with or without a backups block; see the CLI reference.

publish ​

Container ports published on ports of the server itself, for services the proxy cannot serve because they are not HTTP: a database a laptop connects to, a game server. See Expose a service that is not HTTP.

FieldTypeDefaultRule
publish[].portintegerrequiredThe port inside the container, 1 to 65535.
publish[].hostintegerthe same as portThe port on the server, 1 to 65535. Not 80 or 443: the proxy listens there.
publish[].addressstringevery address of the serverAn IP address of the server, IPv4 or IPv6. Not a hostname. Stored in its canonical form: ::ffff:10.0.0.5 becomes 10.0.0.5.
publish[].protocolstringtcptcp or udp. Case-insensitive, trimmed.

At most 20 entries. publish requires deploy.strategy: recreate and replicas: 1: a server port has one holder, so neither two replicas nor the old and the new version side by side can bind it.

yaml
name: postgres
image: postgres:17
replicas: 1
publish:
  - port: 5432        # inside the container
    host: 15432       # on the server; default: the same as port
    address: 10.0.0.5 # default: every address of the server
    protocol: tcp     # or udp
deploy:
  strategy: recreate

Nothing else changes: the container is on the same networks, other applications still reach it at postgres:5432, and the published port comes and goes with the replica.

Within one file, a server port is one binding per protocol and address. port: 5432 and port: 5433, host: 5432 on the same address is an error on the second entry: server port 5432/tcp is published twice. The same port on two different addresses, or as tcp and udp, is two bindings and is allowed.

The agent checks the rest before anything is started, so that a taken port is refused up front rather than found by Docker after the old version has already been stopped:

  • Ports 80, 443, 8080 and 8443, and the port of the agent's own SHIPWICK_LISTEN_ADDR (9000 by default), are Shipwick's: publish[0].host / already published by Shipwick itself (the agent or the proxy).
  • A port that another application's active configuration publishes with the same protocol, on the same address or with either side on every address: publish[0].host / already published by application "postgres".

Both come back as 400 INVALID_CONFIG, like a validation error, from deploy, redeploy and rollback alike.

Published ports bypass the host firewall

On most distributions Docker inserts its own iptables rules ahead of ufw's or firewalld's, so a port published on every address is reachable from the internet whatever the firewall says. Publish only what must be reachable from outside the server, bind it to a private address where one exists (address: 10.0.0.5, a VPN or private-network interface), and leave what only other applications need unpublished: they reach it by name on the shipwick network.

logging ​

Hands replica logs to a Docker logging driver, for shipping them to a collector instead of the server's disk. Without this block, logs go to the server's disk with the json-file driver, capped at 3 × 10 MB per container.

FieldTypeDefaultRule
logging.driverstringrequired when logging is presentOne of json-file, local, syslog, journald, gelf, fluentd, awslogs, splunk. Trimmed; case-sensitive.
logging.optionsmap of string to stringnoneAt most 20 options. A key is lowercase letters, digits and dashes, starting with a letter: ^[a-z][a-z0-9-]*$. A value is at most 1024 characters and contains no newline, carriage return or NUL byte.
yaml
logging:
  driver: gelf
  options:
    gelf-address: udp://logs.example.com:12201
    tag: "{{.Name}}"

The options are the driver's own and reach Docker as written; a number such as max-file: 5 is a fine value. Two kinds of option are checked further, because Shipwick never touches paths on the server:

  • Collector addresses must be scheme://host:port and nothing else: no user, path, query or fragment, and a port from 1 to 65535. The schemes are the driver's: syslog-address takes udp, tcp or tcp+tls; gelf-address takes udp or tcp; fluentd-address takes tcp or tls. unix:// and unixgram:// are refused: a socket is a path on the server.
  • Options that name a file on the server are refused: syslog-tls-ca-cert, syslog-tls-cert, syslog-tls-key, splunk-cafile, splunk-capath. Give the collector a certificate the server already trusts instead.
  • One option is a credential, since 0.10: splunk-token, the HEC token of the splunk driver. It is treated like an env value — encrypted on the server, shown as ******** in every answer of the API and never handed out again, and the mask is refused as its value — and it may be written as ${SPLUNK_TOKEN}, filled in from a secret stored with shipwick secret set like an env value is. An agent before 0.10 stored and returned it in clear; a deployment recorded by one keeps it so until the application is deployed again.

With json-file or local, the 3 × 10 MB caps stay unless you set max-size and max-file yourself. With a remote driver, shipwick logs keeps working through the local copy Docker keeps for docker logs (its dual logging, on by default since Docker 20.10); if that was turned off daemon-wide, shipwick logs shows nothing for the application. Job and shipwick run output always goes through Docker's default driver, whatever logging says.

pre_deploy ​

A command run from the new image, with the application's environment and limits, after the image is pulled and before any replica of the new version exists. For database migrations. See Deployments.

FieldTypeDefaultRule
pre_deploy.commandlist of stringsrequired when pre_deploy is present1 to 256 arguments; the first is not blank; no argument contains a NUL byte or is longer than 4096 bytes. A list, not a string.
pre_deploy.timeoutduration10m1s to 1h
yaml
pre_deploy:
  command: ["dotnet", "Migrate.dll"]
  timeout: 10m

If the command exits non-zero or outlives its timeout, the deployment is FAILED before anything was started; the last lines of its output are kept in the deployment's events, and shipwick deploy prints them under the error. The version that is serving is not touched.

The command runs next to the running version, under recreate too, whose replicas stop only afterwards. What it does must therefore be safe next to the old code: add a column, do not drop one. The container gets no volumes.

jobs ​

Commands run on a schedule, each in a fresh container from the application's image, with its environment, limits and network, and without its volumes. See Run scheduled jobs and one-off commands.

FieldTypeDefaultRule
jobs[].namestringrequiredLowercase letters, digits and dashes, starting and ending with a letter or digit, 1 to 40 characters: ^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$. Unique within the file. pre-deploy and run are reserved: they name the runs of the pre_deploy command and of shipwick run.
jobs[].schedulestringrequiredFive cron fields, read in UTC. Runs of whitespace between fields are collapsed to one space.
jobs[].commandlist of stringsrequiredSame rule as pre_deploy.command: 1 to 256 arguments, the first not blank, none containing a NUL byte or longer than 4096 bytes. A list, not a string.
jobs[].timeoutduration1h1s to 24h

At most 20 jobs per application.

yaml
jobs:
  - name: nightly-report
    schedule: "0 3 * * *"
    command: ["node", "report.js"]
    timeout: 1h
  - name: cleanup
    schedule: "*/15 * * * *"
    command: ["sh", "-c", "find /tmp/cache -mmin +60 -delete"]

The schedule is the classic five fields:

text
┌───────────── minute (0–59)
│ ┌─────────── hour (0–23)
│ │ ┌───────── day of month (1–31)
│ │ │ ┌─────── month (1–12, or jan–dec)
│ │ │ │ ┌───── day of week (0–6, sun–sat; 7 is sunday too)
│ │ │ │ │
0 3 * * *

Every field takes *, a value, a range a-b, a list a,b,c, and a step */n, a-b/n or a/n (from a on, every n). Month and weekday names are accepted in place of numbers, in any case. When both the day of month and the day of week are restricted, either matching is enough, as in every cron since Vixie's. Schedules are read in UTC, whatever the server's time zone. Quote them: an unquoted * at the start of a YAML value is an alias.

A job runs once per firing, at most one run at a time: a run still going when the schedule fires again is left alone and that firing is skipped. A run that outlives its timeout is stopped. A stopped application runs no jobs. A firing that fell while the agent was down is not caught up. The last 50 runs of each job are kept, with the last 200 lines (64 KB) of output; shipwick jobs lists jobs with their last and next run.

restart ​

What the supervisor does when a replica exits or turns unhealthy.

FieldTypeDefaultRule
restart.policystringalwaysOne of always, on-failure, never
ValueBehavior
alwaysRestart a replica that exited, whatever its exit code, and a running replica that turned unhealthy.
on-failureRestart a replica that exited with a non-zero code or was killed for exceeding its memory limit. Leave a replica that exited with code 0 stopped. A running replica that turned unhealthy is restarted.
neverNever restart.
yaml
restart:
  policy: on-failure

Restarts back off: 1s, 2s, 5s, 10s, 30s, then every 5 minutes.

deploy ​

FieldTypeDefaultRule
deploy.strategystringrollingOne of rolling, recreate. Must be recreate when volumes or publish is set.
deploy.stop_timeoutduration10s1s to 10m. How long a replica that is being stopped gets between SIGTERM and SIGKILL. Does not apply to a static application.
ValueBehavior
rollingReplicas are replaced one at a time, each new one only after it proved healthy. The application keeps serving throughout, and both versions serve side by side for a moment.
recreateThe running version is taken out of the proxy and stopped first, then the new one is started and verified. The application is down for as long as the new version takes to start. If the new version fails, the old containers, kept stopped, are started again. For applications whose two versions cannot run side by side: anything with a volume or a published port, or that holds a lock.
yaml
deploy:
  strategy: recreate

With rolling and publish, the error is must be "recreate" for an application that publishes ports: two versions cannot listen on the same server port. With volumes as well, only the volume message is shown.

yaml
deploy:
  stop_timeout: 2m   # WebSockets, long uploads: let them finish

stop_timeout applies wherever Shipwick stops a replica gracefully: a deployment that replaces it, shipwick stop, shipwick delete, the restart of an unhealthy replica. A deployment does not wait for the replaced replicas: once every new replica serves, it is done, and the old containers get their SIGTERM and their time in the background. What the time is used for is the application's business. A process that handles SIGTERM leaves cleanly and usually at once; one that does not keeps running until the time is up and is killed with whatever it was serving, and the application's events say so:

text
The replaced container shipwick_my-api_6_1 did not exit within 10s of SIGTERM and was killed. If its process has no handler for SIGTERM, set init: true and the signal ends it at once; to let it finish its requests, handle SIGTERM in the application; to give it longer, set deploy.stop_timeout

Since 0.6 shipwick stop writes the same line about a replica it had to kill, and the line names init, which is the remedy for a process that never sees the signal. See Deployments.

init ​

Runs Docker's init process as the first process of every container of the application, with the image's own process as its child. The init process passes SIGTERM on and reaps the children the application leaves behind. Since 0.6.

Typeboolean
Requiredno
Defaultfalse
Ruletrue or false. Does not apply to a static application.
yaml
init: true

The kernel hands the first process of a container no signal it has not installed a handler for, which is why a server started as node server.js sits out its whole deploy.stop_timeout and is then killed. Under an init process the application is an ordinary process and ends on SIGTERM at once. The same ten-line Node server, stopped with shipwick stop, took 0.3 seconds with init: true and 10.4 seconds, its whole grace period and then the kill, without. An application that handles SIGTERM to finish its requests still does under an init process; ending at once is what happens to one that does not.

It applies to every container of the application: replicas, the pre_deploy command, jobs and shipwick run.

It is not the default, because an image that brings its own init does not want a second one: s6-overlay refuses to start unless it is the first process, and an image whose entrypoint is tini would run two. Leave it out for such an image.

shipwick init writes init: true into the deploy.yaml of a Node project whose Dockerfile it writes. The event about a container that had to be killed depends on the field: without it, the line under deploy; with it, the signal did arrive and the process took longer than it was given:

text
The replaced container shipwick_my-api_6_1 did not exit within 10s of SIGTERM and was killed. It runs under an init process, so the signal reached it: to give it longer, set deploy.stop_timeout

A value that is not a boolean, init: tini, is a syntax error reported with its line number. Next to static the field is refused, whatever its value: does not apply to a static application: the proxy serves the files, there is no container. See Deployments.

security ​

Takes away what the application does not need, in every container made from it. Each key narrows and none widens: a deploy.yaml with the block is never less confined than one without it. Since 0.8.

yaml
user: "1000:1000"
security:
  read_only: true                  # the root filesystem cannot be written
  tmpfs:                           # scratch space, in memory
    - /tmp
    - path: /var/cache/api
      size: 200mb                  # 1mb to 1gb; 64mb unless set
  capabilities: none               # or the ones to keep: [CHOWN, SETGID, SETUID]
  non_root: true                   # a container that would run as root is refused
KeyDefault
read_onlyfalsetrue mounts the root filesystem read-only in every container of the application. Volumes and tmpfs stay writable
tmpfs[]—Up to 10 directories kept in memory, for what has to be written under a read-only root: a path (/tmp), or {path, size} with size from 1mb to 1gb, 64mb unless set. Empty at every start; mounted nosuid, nodev and noexec, writable by every user; what is written there counts against resources.memory
capabilitiesDocker's default setnone, or a list of the Linux capabilities to keep out of Docker's default set; every other one is dropped. Nothing outside that set is accepted: the key takes away, it cannot add
non_rootfalsetrue refuses to start a container that would run as root: user, or without it the image's USER, has to be a numeric id other than 0

The block holds for every container of the application: replicas, the pre_deploy command, jobs, shipwick run, the container of backups.before_in: container and the one a backup is verified in. shipwick validate shows what it takes away, shipwick init writes it as a commented example, and the spec in API responses carries it.

  • Docker's default set is AUDIT_WRITE, CHOWN, DAC_OVERRIDE, FOWNER, FSETID, KILL, MKNOD, NET_BIND_SERVICE, NET_RAW, SETFCAP, SETGID, SETPCAP, SETUID and SYS_CHROOT. A name may be written in lower case and with CAP_ in front. An application that runs as another user than root and listens on a port above 1024 needs none; what nginx, Node, PostgreSQL and Redis need is in Containers locked down further.
  • capabilities: none and no key are different. none keeps nothing; without the key the containers keep Docker's default set. An empty list is refused rather than read as either.
  • A tmpfs path is an absolute path inside the container, other than /, at which no volume and no other entry is mounted.
  • non_root is checked twice. shipwick validate refuses user: root, the id 0 or a name next to it. What the image says is known once the image is on the server: a deployment of an image that would run as root fails there, after the pull and before anything is started, with the previous version still serving, and the message says what to set.
  • An agent older than 0.8 refuses a file with the block, as it refuses every key it does not know, and shipwick deploy says that the server is older than the file and how to upgrade it.

Next to static the block is refused: does not apply to a static application: the proxy serves the files, there is no container. The seccomp and AppArmor profiles are Docker's defaults with or without the block. See Containers locked down further for what each key protects against.

Units ​

Sizes ​

Used by resources.memory. A whole or decimal number followed by an optional unit.

UnitBytes
none, b1
k, kb, kib1024
m, mb, mib1024²
g, gb, gib1024³

Units are binary, matching Docker's convention: 1gb is 1024 mb. Units are case-insensitive, and whitespace between the number and the unit is allowed. 1.5gb, 512MB and 512 mb are all valid.

Durations ​

Used by health.interval, health.timeout, health.start_period, pre_deploy.timeout, jobs[].timeout, backups.before_timeout and deploy.stop_timeout. A number with a unit, in Go's duration syntax: 500ms, 3s, 1m, 1m30s. Valid units are ns, us, ms, s, m and h. A number without a unit is not valid. Each field has its own range, listed with the field.

CPU ​

resources.cpu is a plain number of cores without a unit: 0.5, 1, 2.

Validation errors ​

All problems are reported at once, by field, so that they can be fixed in one pass:

text
invalid deploy.yaml

port:
  invalid value 99999
  expected: a number between 1 and 65535

resources.memory:
  invalid value "abc"
  expected: 128mb, 512mb, 1gb, ...

Each entry names the field by its dotted path (resources.memory, env.MY_VAR, volumes[0].path, publish[1].host, logging.options.gelf-address, jobs[0].schedule, proxy.basic_auth[0].password, proxy.headers.X-Frame-Options), says what is wrong, and where possible lists what is expected.

Other forms the report takes:

ProblemReported as
A required field is missingname: / is required
An image next to buildimage: / is built here; remove image or build, expected build: . alone, or image: alone
A build path that is absolute or leaves the projectbuild.context: / invalid value "/srv/app": must be relative to deploy.yaml; invalid value "../app": must stay inside the directory of deploy.yaml; build.dockerfile: / invalid value "/Dockerfile": must be relative to the context; invalid value "../Dockerfile": must stay inside the context, expected Dockerfile, or a file in the context such as docker/Dockerfile.prod
An unknown key under buildline 5: / unknown field "dockerfil". Since 0.10
build and static togetherbuild: / cannot be combined with static: a static application has no image to build
A static application without a domaindomain: / is required for a static application: the proxy serves the files at it
A container field next to staticport: / does not apply to a static application: the proxy serves the files, there is no container; the same on backups, deploy.stop_timeout, init and security
A static folder that is absolute or leaves the projectstatic: / must be a relative path: the folder is found next to deploy.yaml; must stay inside the directory of deploy.yaml, expected dist/, build/, out/ — a folder relative to deploy.yaml
A fallback without a folderstatic.dir: / is required: the folder the fallback page is in, expected dist
A fallback that is not a file in the folderstatic.fallback: / invalid value "/index.html": must be relative to the folder; invalid value "../index.html": name a file inside the folder, with letters, digits, dots, dashes, underscores and tildes between the slashes, expected index.html, 200.html, app/index.html — a file in the folder
An unknown key under staticline 3: / unknown field "fallbak"
A start_period out of rangehealth.start_period: / invalid value "2h": out of range, expected 30s, 1m, 5m, ... (up to 30m)
A reserved application namename: / "caddy" is reserved for Shipwick's own services
port missing while domain is setport: / is required when domain is set
port missing while health.path is setport: / is required when health is set
Another application's built imageimage: / shipwick.local/other:20260927-153000-a1b2 was built for other and runs for other alone; run shipwick deploy from that project to deploy it, or name an image of my-api, expected shipwick.local/my-api:…. Since 0.10: an image under shipwick.local must be the application's own, with or without build, and the agent checks it again on a redeploy
An unknown fieldline 7: / unknown field "replica"
A value of the wrong YAML typeline 3: / cannot unmarshal … into a number
entrypoint or command that is neither a string nor a listline 3: / expected a string or a list of strings, not a map
An empty entrypoint or commandcommand: / must not be empty; omit it to keep the image's own
Too many arguments in entrypoint or commandcommand: / too many arguments (65), expected at most 64
A newline or NUL byte in an argumentcommand[0]: / must not contain newlines or NUL bytes
An invalid useruser: / invalid value "App", expected a user name or id, with or without a group: app, 1000, 1000:1000
aliases or redirects without domainaliases: / requires domain: aliases are served like it; redirects: / requires domain: redirects are sent to it
More than 20 aliases or redirectsaliases: / too many (21), expected at most 20
An empty hostnameredirects[0]: / is empty, expected a hostname, e.g. www.example.com
A hostname with a scheme, port or pathaliases[0]: / invalid value "api.example.com/v1": not a valid hostname
A hostname listed twicealiases[0]: / "example.com" is already listed under domain; redirects[1]: / "a.example.com" is already listed under aliases[0], expected each hostname once
A wildcard that is more than one leading labeldomain: / invalid value "*.*.example.com": a wildcard is one leading label and nothing else, expected api.example.com, *.example.com
A wildcard among the redirectsredirects[0]: / invalid value "*.example.com": not a valid hostname
Redirects next to a wildcard domainredirects: / cannot be sent to a wildcard domain, expected domain: example.com, with the wildcard under aliases
path without domainpath: / requires domain: a path is a part of it, expected domain: example.com
An invalid pathpath: / invalid value "api": must start with /; invalid value "/api/": must not end with /; invalid value "/api v2": use letters, digits, dots, dashes, underscores and tildes between the slashes; invalid value "/api/../x": must not contain . or .. segments; invalid value: longer than 200 characters, expected /api, /docs/v2, ...
proxy without domainproxy: / requires domain: it says what the proxy does with the requests for it, expected domain: example.com
An unknown key under proxyline 12: / unknown field "header"
strip_prefix without pathproxy.strip_prefix: / requires path: it is the prefix that is removed, expected path: /api
More than 50 headersproxy.headers: / too many (51), expected at most 50
An invalid header nameproxy.headers: / invalid header name "X Frame", expected letters, digits and dashes, e.g. X-Frame-Options
A header that belongs to the connectionproxy.headers.Content-Length: / belongs to the connection, and the proxy writes it itself, expected a header about the content, e.g. X-Frame-Options, Cache-Control
A header listed twice in different caseproxy.headers.x-frame-options: / is the same header as X-Frame-Options: names are compared without regard to case, expected each header once
An empty, oversized or multi-line header valueproxy.headers.X-Frame-Options: / value must not be empty; value is too long (4097 characters), expected at most 4096; value must not contain control characters or newlines
More than 20 accountsproxy.basic_auth: / too many (21), expected at most 20
An account's path outside the application'sproxy.basic_auth[0].path: / "/admin" is outside path /api, which is all this application serves, expected /api/admin
An account without a username, or with an invalid oneproxy.basic_auth[0].username: / is required, expected admin; is too long (256 characters), expected at most 255; invalid value "a:b": must not contain a colon or control characters; since 0.10 invalid value "{env.HOME}": must not contain braces, which the proxy would read as a placeholder
A username listed twice for one pathproxy.basic_auth[1].username: / "admin" is listed twice for the same path, expected one entry for each user of a path
A missing or unusable passwordproxy.basic_auth[0].password: / is required; is too short: at least 8 characters; is too long: at most 72 bytes; must not contain control characters, expected ${ADMIN_PASSWORD}, with the value in the environment, in --env-file or stored with shipwick secret set. The password is never repeated.
More than 100 path redirectsproxy.redirects: / too many (101), expected at most 100
A redirect without from, or from everythingproxy.redirects[0].from: / is required; must be a path below /: redirecting everything would leave nothing to serve, expected /old
A path redirected twiceproxy.redirects[1].from: / "/old" is redirected twice, expected one redirect for each path
A redirect without to, or to something else than a path or an https:// URLproxy.redirects[0].to: / is required; invalid value "http://example.org/new": must be a path starting with / or an https:// URL; invalid value "//example.org/new": a path starts with one slash; for another host use https://, expected /new, https://example.org/new
A redirect target with a space or bracesproxy.redirects[0].to: / invalid value "/new page": must not contain whitespace, control characters, braces or backslashes
An unknown redirect statusproxy.redirects[0].status: / invalid value 303, expected 301, 302, 307, 308
A redirect to itselfproxy.redirects[0].to: / redirects /old to itself, expected another path, or an https:// URL
Redirects that lead in a circleproxy.redirects[0].to: / leads back to /old through the other redirects: a browser would follow them forever, expected a path that is not redirected
A duration out of rangehealth.interval: / invalid value "10m": out of range
An invalid environment variable nameenv.my-var: / invalid variable name
A health block without a kindhealth: / one of path, tcp or command is required
A health block with two kindshealth: / path and tcp are set; a health check is one of path, tcp or command
A health.tcp port out of rangehealth.tcp: / invalid value 0, expected the port your application listens on, e.g. 5432
An empty or oversized health.commandhealth.command: / must not be empty; too many arguments (65), expected at most 64
An empty argument or a NUL byte in health.commandhealth.command[1]: / must not be empty; must not contain NUL bytes
An unknown deployment strategydeploy.strategy: / invalid value "blue-green", expected rolling, recreate
A stop_timeout out of rangedeploy.stop_timeout: / invalid value "15m": out of range, expected 10s, 30s, 5m, ... (1s to 10m)
An init that is not a booleanline 3: / cannot unmarshal … into the expected type
init next to staticinit: / does not apply to a static application: the proxy serves the files, there is no container
A key of security that does not existsecurity: / expected read_only, tmpfs, capabilities, non_root
A capability outside Docker's default setsecurity.capabilities[0]: / invalid value "SYS_ADMIN": not in Docker's default set, and nothing is added to it
A capability listed twicesecurity.capabilities[1]: / "CHOWN" is listed twice
An empty list of capabilitiessecurity.capabilities: / must not be empty; write none to keep no capability, or omit it to keep Docker's default set
A tmpfs path that is not absolute, or is /security.tmpfs[0].path: / invalid value "tmp", expected an absolute path inside the container, e.g. /tmp
A tmpfs path a volume or another entry is mounted atsecurity.tmpfs[1].path: / "/data" is already mounted: …
A tmpfs size outside 1 MB to 1 GBsecurity.tmpfs[0].size: / invalid value "2gb": out of range
More than 10 tmpfs entriessecurity.tmpfs: / too many (11), expected at most 10
user: root, the id 0 or a name under non_root: trueuser: / invalid value "app" next to security.non_root: it is a name, and which id a name stands for is in the image's /etc/passwd, which is not read
More than 10 volumesvolumes: / too many (11), expected at most 10
A volume name used twicevolumes[1].name: / "data" is used twice
A volume path that is not absolute and cleanvolumes[0].path: / invalid value "data/", expected an absolute path inside the container, e.g. /var/lib/postgresql/data
A volume path used twicevolumes[1].path: / "/data" is mounted twice
Volumes without recreatedeploy.strategy: / must be "recreate" for an application with volumes: two versions cannot write the same files at once
Volumes with more than one replicareplicas: / must be 1 for an application with volumes, got 2: replicas cannot share a volume
backups that is not a blockbackups: / must be a block with a schedule
An unknown key under backupsbackups: / unknown field "schedul", expected schedule, keep, before, before_timeout, before_in, stop
backups without a schedulebackups.schedule: / is required, expected "0 3 * * *" (minute hour day-of-month month day-of-week, in UTC)
An invalid backup schedulebackups.schedule: / invalid value "61 * * * *": minute: value 61 out of range 0-59, expected five cron fields in UTC, e.g. "0 3 * * *" (every day at 03:00)
A keep out of rangebackups.keep: / invalid value 0, expected a number between 1 and 365
An empty or oversized before commandbackups.before: / is required; too many arguments (257); argument 2 is longer than 4096 bytes; argument 2 must not contain NUL bytes
A before_timeout without beforebackups.before_timeout: / needs backups.before: it is that command's time limit, expected 10m, 1h, 6h, ... (1s to 24h)
A before_timeout out of range, or without a unitbackups.before_timeout: / invalid value "25h": out of range; invalid value "90", expected 10m, 1h, 6h, ... (1s to 24h)
A before_in without beforebackups.before_in: / needs backups.before: it says where that command runs, expected replica (inside the running replica), container (in a container of its own, which can be ended)
A before_in that is neitherbackups.before_in: / invalid value "sidecar", with the same expectation
"********" as an env value or a basic-auth passwordenv.LOG_LEVEL: / ******** is what the server shows in the place of this value, not the value, expected the value itself, or ${NAME} with the value stored by shipwick secret set NAME. Since 0.7
backups without volumesbackups: / needs volumes: a backup is an archive of the application's volumes
Published ports without recreatedeploy.strategy: / must be "recreate" for an application that publishes ports: two versions cannot listen on the same server port
Published ports with more than one replicareplicas: / must be 1 for an application that publishes ports, got 2: replicas cannot share a server port
More than 20 published portspublish: / too many (21), expected at most 20
A publish entry without portpublish[0].port: / is required, expected the port your application listens on, e.g. 5432
A published port out of rangepublish[0].port: / invalid value 70000; publish[0].host: / invalid value 0, expected a number between 1 and 65535
A server port the proxy listens onpublish[0].host: / invalid value 80: the proxy listens there, expected another server port, e.g. 15432
An unknown protocolpublish[0].protocol: / invalid value "sctp", expected tcp, udp
An address that is not an IP addresspublish[0].address: / invalid value "db.internal", expected an address of the server, e.g. 10.0.0.5
A server port published twicepublish[1].host: / server port 5432/tcp is published twice, expected a different server port for each entry
logging without a driverlogging.driver: / is required when logging is set, expected json-file, local, syslog, journald, gelf, fluentd, awslogs, splunk
An unknown logging driverlogging.driver: / invalid value "GELF"
More than 20 logging optionslogging.options: / too many (21), expected at most 20
An invalid option namelogging.options.Gelf-Address: / invalid option name, expected lowercase letters, digits and dashes, e.g. gelf-address
An option that names a file on the serverlogging.options.syslog-tls-ca-cert: / names a file on the server, which Shipwick never reads
An option value too longlogging.options.tag: / value is too long (1025 characters), expected at most 1024
A newline or NUL byte in an option valuelogging.options.tag: / value must not contain newlines or NUL bytes
A collector address without a scheme or portlogging.options.gelf-address: / invalid value "logs.example.com:12201": must be scheme://host:port
A collector address that is a socketlogging.options.syslog-address: / invalid value "unix:///dev/log": a socket is a path on the server, which Shipwick never mounts; use a network address
A scheme the driver does not speaklogging.options.gelf-address: / invalid value "tcp+tls://logs.example.com:12201": unknown scheme "tcp+tls", use udp, tcp
A collector address with a path or credentialslogging.options.fluentd-address: / invalid value "tcp://logs.example.com:24224/x": must be scheme://host:port, nothing after the port
A collector address with a bad portlogging.options.gelf-address: / invalid value "udp://logs.example.com:99999": port must be a number between 1 and 65535
A pre_deploy block without a commandpre_deploy.command: / is required, expected ["dotnet", "Migrate.dll"]
A command with too many or oversized argumentspre_deploy.command: / too many arguments (257); argument 2 is longer than 4096 bytes; argument 2 must not contain NUL bytes
A pre_deploy timeout out of rangepre_deploy.timeout: / invalid value "2h": out of range, expected 30s, 10m, 1h, ... (1s to 1h)
More than 20 jobsjobs: / too many (21), expected at most 20
A job without a namejobs[0].name: / is required, expected nightly-report
An invalid job namejobs[0].name: / invalid value "Nightly", expected lowercase letters, digits and dashes, e.g. nightly-report (max 40 characters)
A reserved job namejobs[0].name: / "run" is reserved, expected another name, e.g. nightly-report
A job name used twicejobs[1].name: / "cleanup" is used twice, expected a different name for each job
A job without a schedulejobs[0].schedule: / is required, expected "0 3 * * *" (minute hour day-of-month month day-of-week, in UTC)
An invalid schedulejobs[0].schedule: / invalid value "61 * * * *": minute: value 61 out of range 0-59; invalid value "* * * * * *": expected 5 fields (minute hour day-of-month month day-of-week), got 6
A job without a commandjobs[0].command: / is required, expected ["node", "report.js"]
A job timeout out of rangejobs[0].timeout: / invalid value "25h": out of range, expected 5m, 1h, 12h, ... (1s to 24h)
An empty filedeploy.yaml: / file is empty
Several YAML documents in one filedeploy.yaml: / multiple YAML documents are not supported; describe one application per file
A file over 64 KBdeploy.yaml: / file is too large (max 64 KB)
A hostname in use, refused by the agentdomain: / already served by application "web"; aliases[1]: / already served by Shipwick itself (the agent or the dashboard)
A path of a hostname in use, refused by the agentpath: / example.com/api is already served by application "api"; applications share a domain under different paths; aliases[0]: / api.example.com/api is already served by application "api"
A wildcard no certificate can be had for, refused by the agentaliases[0]: / a certificate for a wildcard is issued only through a DNS record, and the agent is not set up for that, expected SHIPWICK_CLOUDFLARE_API_TOKEN on the agent, or a certificate of your own: shipwick cert set '*.example.com' --cert fullchain.pem --key privkey.pem
A stored secret that cannot be used as a password, refused by the agentproxy.basic_auth[0].password: / with ${ADMIN_PASSWORD} filled in from the server's secrets, the password is too short: at least 8 characters, expected shipwick secret set ADMIN_PASSWORD
A server port in use, refused by the agentpublish[0].host: / already published by application "postgres"; already published by Shipwick itself (the agent or the proxy)

Unknown fields do not hide other mistakes: when they are the only syntax problem, the rest of the file is still validated and everything is reported together.

An unset ${NAME} outside env is reported by shipwick before validation, since the document cannot be validated without it: deploy.yaml: refers to ${DATABASE_PASSWORD}, which is not set. An env value whose ${NAME} is set neither where shipwick runs nor among the server's secrets is refused by the agent in the same shape: env.DATABASE_URL: / refers to ${DATABASE_PASSWORD}, which is not set where shipwick runs and not stored on the server, expected shipwick secret set DATABASE_PASSWORD. A basic-auth password is reported the same way, on proxy.basic_auth[0].password.

The agent returns the same information in the API's error envelope, as 400 INVALID_CONFIG with one object per problem in details.fields:

json
{
  "error": {
    "code": "INVALID_CONFIG",
    "message": "invalid deploy.yaml",
    "details": {
      "fields": [
        { "field": "resources.memory", "message": "invalid value \"abc\"", "expected": "128mb, 512mb, 1gb, ..." }
      ]
    }
  }
}

The checks only the agent can make — a hostname, a path of one or a server port already in use, a wildcard without a certificate, a secret that is not stored — come back in the same shape. A hostname or a server port in use is refused by deploy, redeploy and rollback alike. shipwick deploy asks the agent for them before it builds an image or uploads a folder, so they are reported before the work, not after it. shipwick renders an agent-side rejection exactly like a local one.

Full example ​

yaml
# deploy.yaml — everything Shipwick needs to run your application.
# Only `name` and `image` (or `build` in its place) are required.
#
# A built frontend needs no container: name the folder instead of an image and
# Caddy serves it as it is. Only `name`, `static` and `domain` then apply, with
# `aliases` and `redirects`; run the build before `shipwick deploy`.
#   name: web
#   static: dist/
#   domain: example.com
# A single-page application answers every path that names no file with one page:
#   static: {dir: dist/, fallback: index.html}

# Lowercase letters, digits and dashes. Identifies the application on the server.
name: my-api

# Any image reference Docker understands. For a private registry, give the
# server a credential once: shipwick registry login ghcr.io --username <name>
# Pin a version tag: deployments are recorded by it (1.4.2 here).
image: ghcr.io/company/my-api:1.4.2

# No registry? Build the image on your machine instead: `shipwick deploy` runs
# docker build here, for the server's architecture, and sends the image to the
# server. The context is relative to this file, the Dockerfile to the
# context. Replaces `image`.
# build: .
# build:
#   context: .               # default: the directory of this file
#   dockerfile: Dockerfile   # default; relative to the context

# Run something other than the image's default: these replace its ENTRYPOINT,
# CMD and USER. A string is one argument; use a list for several. Nothing is
# split on spaces or passed through a shell.
# entrypoint: ["dotnet"]
# command: ["App.dll", "--urls", "http://0.0.0.0:8080"]
# user: "1000:1000"

# The port your application listens on inside the container. It is never
# published on the host; the reverse proxy reaches it over a private network.
# Required when `domain` or `health` is set.
port: 8080

# Public hostname. Shipwick configures Caddy to serve it over HTTPS.
domain: api.example.com

# More hostnames served exactly like `domain`, and hostnames redirected to it
# (308, same path and query; below `path`, if the application has one) — www,
# an old domain. Each gets a certificate.
# `domain` and aliases may be a wildcard, "*.example.com", when the agent has
# a Cloudflare API token or you supplied a certificate that covers it
# (shipwick cert set).
# aliases: [api2.example.com]
# redirects: [www.api.example.com]

# Serve only one path of the domain, and everything under it; another
# application takes another path, or the rest. The longest path wins.
# path: /api

# What the proxy does for this application besides passing requests on.
# Every path here is the path as the visitor asks for it.
# proxy:
#   strip_prefix: true              # the application sees /users for /api/users; needs path
#   headers:                        # set on every response
#     X-Frame-Options: DENY
#     Strict-Transport-Security: max-age=31536000
#   basic_auth:
#     - path: /api/admin            # optional; without it, the whole application
#       username: admin
#       password: ${ADMIN_PASSWORD} # a secret, filled in like an env value
#   redirects:
#     - from: /api/old
#       to: /api/new                # or an https:// URL
#       status: 308                 # 301, 302, 307 or 308; default 308

# Number of identical containers to run. Default: 1.
replicas: 2

# Environment variables. Values are stored on the server, never logged, and
# masked in API responses. ${NAME} is filled in when you deploy, so that secrets
# never have to be in this file: by the CLI from its environment or --env-file,
# else by the agent from the secrets stored with `shipwick secret set NAME`.
# $${NAME} is a literal ${NAME}.
# Other applications on the server are reached by name: postgres:5432.
env:
  DATABASE_URL: postgres://app:${DATABASE_PASSWORD}@postgres:5432/app
  LOG_LEVEL: info

# HTTP health check. A replica is healthy when `path` answers 2xx.
#
# Deploying: new replicas get start_period + interval × retries (30s here) to
# answer once; if they never do, the deployment fails and the old version
# keeps running. Slow starter — a JVM, a migration on boot? Set start_period.
#
# Running: a replica that fails `retries` checks in a row is restarted, and
# gets the same time to come up again.
#
# Not HTTP? Use exactly one of path, tcp or command:
#   tcp: 5432                                  # the port accepts a connection
#   command: ["pg_isready", "-U", "postgres"]  # exit 0 inside the replica
health:
  path: /health
  interval: 10s # default 10s
  timeout: 3s   # default 3s
  retries: 3    # default 3
  # start_period: 1m   # extra time to come up before failed checks count (up to 30m)

# Per-replica limits. Omit for unlimited.
resources:
  cpu: 2        # cores; fractions allowed: 0.5
  memory: 1gb   # 128mb, 512mb, 1gb, ...

# What to do when a replica exits or turns unhealthy:
#   always (default) | on-failure (non-zero exit / out of memory only) | never
# Restarts back off (1s, 2s, 5s, 10s, 30s, then every 5m): no hot crash loops.
restart:
  policy: always

deploy:
  strategy: rolling

# Data that must outlive deployments — a database. Named volumes belong to the
# application and are kept across redeployments, rollbacks and delete. They
# need replicas: 1 and the recreate strategy: two versions on one volume is
# how data gets lost.
# volumes:
#   - name: data
#     path: /var/lib/postgresql/data

# Backups of the volumes, taken by the server on a schedule (five cron fields,
# UTC) and kept there and, when the agent has one, in an S3 bucket. `before`
# runs inside the running replica first — a dump, a checkpoint — and a non-zero
# exit fails the backup; `stop: true` stops the application while the archive
# is taken. `shipwick backups` lists them, `shipwick backups verify` proves
# that one restores. With `before_in: container` the command runs in a
# container of its own beside the replica and is ended at before_timeout; it
# reaches the replica as localhost and sees the volumes, not the replica's
# other files, so pg_dump needs `-h localhost` there.
# backups:
#   schedule: "0 3 * * *"
#   keep: 7       # successful backups kept; default 7, up to 365
#   before: ["pg_dump", "-U", "postgres", "-f", "/var/lib/postgresql/data/backup.sql", "app"]
#   before_timeout: 1h   # how long `before` may run; default 1h, up to 24h
#   before_in: replica   # replica (default) | container
#   stop: false   # default false

# Ports that are not HTTP, published on the server itself: a database reached
# from outside the server, a game server. Needs replicas: 1 and the recreate
# strategy: a server port has one holder. Published ports bypass the host
# firewall on most distributions; bind to a private address where you can.
# publish:
#   - port: 5432        # inside the container
#     host: 15432       # on the server; default: the same as port
#     address: 10.0.0.5 # default: every address of the server
#     protocol: tcp     # or udp

# rolling (default): replicas are replaced one at a time, the application keeps
# serving. recreate: the running version is stopped before the new one starts;
# required with volumes and publish.
#
# stop_timeout: how long a replica that is being stopped — replaced by a
# deployment, or by `shipwick stop` — gets to finish what it has in hand after
# SIGTERM, before it is killed. Default 10s, up to 10m. Raise it for WebSockets
# or long uploads; the application has to handle SIGTERM for the time to be of
# use.
# deploy:
#   strategy: recreate
#   stop_timeout: 2m

# Docker's init process in front of the image's own, in every container of
# the application: it passes SIGTERM on and reaps children. For a process that
# does not handle the signal as the container's first process — Node started
# as `node server.js` — and is otherwise killed when stop_timeout ends. Leave
# it out for an image that brings its own init (tini, s6-overlay).
# init: true

# Take away what the application does not need, in every container made from
# it: replicas, the pre_deploy hook, jobs, one-off commands. Each key narrows
# and none widens; leave out the ones the application cannot live with.
#
# read_only: the root filesystem cannot be written. Volumes can, and so can
# every tmpfs path: a directory in memory, empty at each start, mounted
# nosuid, nodev and noexec, counted against resources.memory. A path alone
# gets 64mb; size is 1mb to 1gb. nginx needs /var/cache/nginx and /var/run.
#
# capabilities: `none`, or the ones to keep out of Docker's default set
# (AUDIT_WRITE CHOWN DAC_OVERRIDE FOWNER FSETID KILL MKNOD NET_BIND_SERVICE
# NET_RAW SETFCAP SETGID SETPCAP SETUID SYS_CHROOT); the rest is dropped. An
# application that runs as another user than root on a port above 1024 needs
# none; nginx started as root needs [CHOWN, SETGID, SETUID].
#
# non_root: a container that would run as root is refused, and the deployment
# fails before anything starts. The user — `user` above, or else the image's
# USER — must be a numeric id other than 0: a name cannot be checked.
# security:
#   read_only: true
#   tmpfs:
#     - /tmp
#     - path: /var/cache/api
#       size: 200mb
#   capabilities: none
#   non_root: true

# Ship logs to a collector instead of the server's disk: json-file (default),
# local, syslog, journald, gelf, fluentd, awslogs or splunk, with the driver's
# own options. Addresses are scheme://host:port; no sockets or files on the
# server. `shipwick logs` keeps working through the copy Docker keeps locally.
# logging:
#   driver: gelf
#   options:
#     gelf-address: udp://logs.example.com:12201
#     tag: "{{.Name}}"

# Run from the new image, with the env above, after the pull and before any
# replica of the new version starts — database migrations. A non-zero exit
# fails the deployment before anything was touched. It runs next to the version
# still serving, so what it does must be compatible with that version.
# pre_deploy:
#   command: ["dotnet", "Migrate.dll"]
#   timeout: 10m # default 10m, up to 1h

# Commands on a schedule, each in a one-off container from this image with the
# env above (no volumes). Five cron fields, read in UTC. One run of a job at a
# time; `shipwick jobs` shows how they are doing.
# jobs:
#   - name: nightly-report
#     schedule: "0 3 * * *"
#     command: ["node", "report.js"]
#     timeout: 1h # default 1h, up to 24h
#   - name: cleanup
#     schedule: "*/15 * * * *"
#     command: ["sh", "-c", "find /tmp/cache -mmin +60 -delete"]

Several applications: shipwick.yaml ​

A project with more than one service — a database, an API, a front end — describes them all in one shipwick.yaml: an apps list in which every entry is a complete deploy.yaml plus after, the names of the entries it must wait for.

yaml
# shipwick.yaml — several applications in one file.
apps:
  # Nothing to wait for: starts at once, together with `web`.
  - name: postgres
    image: postgres:17
    port: 5432
    env:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - name: data
        path: /var/lib/postgresql/data
    health:
      tcp: 5432
    deploy:
      strategy: recreate

  # Starts when `postgres` has deployed. If postgres fails, api is skipped and
  # the command exits non-zero; web is not affected.
  - name: api
    image: ghcr.io/company/api:2.3.0
    port: 8080
    domain: api.example.com
    env:
      DATABASE_URL: postgres://app:${POSTGRES_PASSWORD}@postgres:5432/app
    health:
      path: /health
    pre_deploy:
      command: ["./migrate", "up"]
    after: [postgres]

  # Independent of the others: reaches the API at http://api:8080 whenever it
  # is there, so it need not wait for it.
  - name: web
    image: ghcr.io/company/web:2.3.0
    port: 3000
    domain: example.com
    redirects: [www.example.com]
appsRequired, and the only top-level key: any other is cannot be set at the top of shipwick.yaml; move it into an entry under apps. A list of 1 to 50 entries.
An entryA complete deploy.yaml, validated by the same rules, so every field on this page can be set in one, path, proxy and backups included; problems are reported with the entry's index in front, apps[1].port. Names must be unique within the file. build and static paths are relative to shipwick.yaml.
afterA list of names of other entries in the file. An unknown name, an entry that waits for itself, or a cycle through several entries is an error on apps[i].after.

shipwick deploy uses the file when there is no deploy.yaml in the directory; -f shipwick.yaml names it explicitly, and it cannot be combined with other -f files. Since 0.8 shipwick deploy api deploys the named application of the file and nothing else, and shipwick deploy api web those two: after still orders the named ones, an application that is left out is not waited for and is assumed to be running, which the output says in one line, and --image applies when exactly one is named. shipwick validate takes the same names. See shipwick deploy. Applications whose dependencies are done start at once, up to four at a time (--parallel N): postgres and web above start together, api when postgres has deployed. Every line of output carries the name of the application it belongs to. An application whose dependency did not deploy is skipped, the others finish, and the command exits non-zero if any failed or was skipped. ${NAME} placeholders work in every entry, --image does not apply, and shipwick validate checks the file and prints the order.

The agent never sees the file. Each entry is an ordinary deployment with its own record, lock, health checks and rollback; the CLI holds the order. after is about readiness, not reachability: names on the services network resolve whatever the order, so after: [postgres] belongs on an application that would exit without its database, not on every consumer of another service. Several deploy.yaml files — shipwick deploy -f api/deploy.yaml -f web/deploy.yaml — still deploy one after the other, in the order given, stopping at the first failure.