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
name: my-api
image: ghcr.io/company/my-api:1.4.2
port: 8080
domain: api.example.com
replicas: 2- Only
nameandimageare required, orbuildin place ofimage. A folder the proxy serves itself needsname,staticanddomain, 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.yamlinstead. - The maximum size is 64 KB.
- Unknown fields are errors. A misspelled key is reported, not ignored.
shipwicklooks fordeploy.yamlin the current directory, then forshipwick.yaml;-f/--fileselects another file, and can be repeated to deploy several applications in order.shipwick initwrites a starter file, with a Dockerfile for a project it recognises, andshipwick validatechecks 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}:
env:
DATABASE_URL: postgres://app:${DATABASE_PASSWORD}@postgres:5432/appTwo 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
| Field | Type | Required | Default |
|---|---|---|---|
name | string | yes | |
image | string | unless build or static is set | |
build | ., a folder, or {context, dockerfile} | in place of image | |
build.context | string | no | ., the directory of deploy.yaml |
build.dockerfile | string | no | Dockerfile |
static | a folder, or {dir, fallback} | in place of image; requires domain | |
static.dir | string | with static as a map | |
static.fallback | string | no | none: a path that names no file is a 404 |
entrypoint | list of strings, or one string | no | the image's ENTRYPOINT |
command | list of strings, or one string | no | the image's CMD |
user | string | no | the image's USER |
port | integer | with domain or health.path | none |
domain | string | no | none |
aliases | list of strings | no | none |
redirects | list of strings | no | none |
path | string | no; requires domain | the whole domain |
proxy.strip_prefix | boolean | no; requires path | false |
proxy.headers | map of string to string | no | none |
proxy.basic_auth[].path | string | no | the whole application |
proxy.basic_auth[].username | string | with proxy.basic_auth | |
proxy.basic_auth[].password | string | with proxy.basic_auth | |
proxy.redirects[].from | string | with proxy.redirects | |
proxy.redirects[].to | string | with proxy.redirects | |
proxy.redirects[].status | integer | no | 308 |
replicas | integer | no | 1 |
env | map of string to string | no | none |
health.path | string | one of path, tcp, command with health | |
health.tcp | integer | one of path, tcp, command with health | |
health.command | list of strings | one of path, tcp, command with health | |
health.interval | duration | no | 10s |
health.timeout | duration | no | 3s |
health.retries | integer | no | 3 |
health.start_period | duration | no | 0s |
resources.cpu | number | no | unlimited |
resources.memory | size | no | unlimited |
volumes[].name | string | with volumes | |
volumes[].path | string | with volumes | |
backups.schedule | string | with backups; requires volumes | |
backups.keep | integer | no | 7 |
backups.before | list of strings | no | none |
backups.before_timeout | duration | no; requires backups.before | 1h |
backups.before_in | string | no; requires backups.before | replica |
backups.stop | boolean | no | false |
publish[].port | integer | with publish | |
publish[].host | integer | no | the same as port |
publish[].address | string | no | every address of the server |
publish[].protocol | string | no | tcp |
logging.driver | string | with logging | |
logging.options | map of string to string | no | none |
pre_deploy.command | list of strings | with pre_deploy | |
pre_deploy.timeout | duration | no | 10m |
jobs[].name | string | with jobs | |
jobs[].schedule | string | with jobs | |
jobs[].command | list of strings | with jobs | |
jobs[].timeout | duration | no | 1h |
restart.policy | string | no | always |
deploy.strategy | string | no | rolling |
deploy.stop_timeout | duration | no | 10s |
init | boolean | no | false |
security.read_only | boolean | no | false |
security.tmpfs[] | list of paths, or of {path, size} | no | |
security.capabilities | none, or a list of strings | no | Docker's default set |
security.non_root | boolean | no | false |
after | list of strings | no; 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.
| Type | string |
| Required | yes |
| Rule | A 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])?$ |
| Reserved | agent, caddy, dashboard and localhost cannot be application names. They belong to Shipwick's own containers on the network the applications share. |
name: my-apiUnderscores 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.
| Type | string |
| Required | yes, unless build or static is set. Next to build, an image is an error: is built here; remove image or build. |
| Rule | A well-formed image reference without whitespace. Leading and trailing whitespace is trimmed. |
image: ghcr.io/company/my-api:1.4.2The deployment's version is derived from the reference:
| Reference | Version |
|---|---|
With a tag: ghcr.io/company/my-api:1.4.2 | The tag: 1.4.2 |
With a digest only: my-api@sha256:4f2a… | sha256: and the first 12 hex characters of the digest |
With neither: nginx | latest |
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.
| Type | A string, the build context; or a map with context and dockerfile |
| Required | no. Replaces image; cannot be combined with static. |
build.context | Default .. The directory handed to docker build, relative to deploy.yaml: . for its own directory, or a folder in it such as api. |
build.dockerfile | Default Dockerfile. Relative to the context. |
| Rule | Both 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 keys | Since 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. |
build: .build:
context: .
dockerfile: docker/Dockerfile.prodA 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.
| Type | A string, the folder; or a map with dir and fallback |
| Required | no. Replaces image. Requires domain: is required for a static application: the proxy serves the files at it. |
static.dir | Required 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.fallback | A 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. |
| Excludes | image, 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. |
name: web
static: dist/
domain: example.com
redirects: [www.example.com]static:
dir: dist/
fallback: index.htmlRun 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.
| Type | list of strings, or one string |
| Required | no |
| Default | the image's ENTRYPOINT |
| Rule | 1 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. |
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.
| Type | list of strings, or one string |
| Required | no |
| Default | the image's CMD |
| Rule | 1 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. |
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.
| Type | string |
| Required | no |
| Default | the image's USER |
| Rule | A 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}))?$ |
| Normalization | Leading and trailing whitespace is trimmed. |
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.
| Type | integer |
| Required | when domain or health.path is set |
| Rule | 1 to 65535 |
port: 8080A 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.
| Type | string |
| Required | no. Requires port. |
| Rule | A 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". |
| Normalization | Trimmed and converted to lowercase. |
domain: api.example.comMore 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.
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.
| Type | list of strings |
| Required | no. Requires domain. |
| Rule | At most 20 entries. Each is a hostname by the same rule as domain, wildcards included, and is listed once across domain, aliases and redirects. |
| Normalization | Each entry is trimmed and converted to lowercase. The order is kept. |
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.
| Type | list of strings |
| Required | no. Requires domain, and one that is not a wildcard: cannot be sent to a wildcard domain. |
| Rule | At most 20 entries. Each is a plain hostname, never a wildcard, and is listed once across domain, aliases and redirects. |
| Normalization | Each entry is trimmed and converted to lowercase. The order is kept. |
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.
| Type | string |
| Required | no. Requires domain. |
| Default | the whole domain. path: / means the same. |
| Rule | Starts 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._~-]+)+$ |
| Normalization | Leading and trailing whitespace is trimmed. |
name: api # example.com/api and everything under it
domain: example.com
path: /apiname: web # the rest of example.com
domain: example.comThe 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.
| Field | Type | Default | Rule |
|---|---|---|---|
proxy.strip_prefix | boolean | false | Requires path. Removes it from a request before the application sees it: /api/users arrives as /users. |
proxy.headers | map of string to string | none | At 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[].path | string | the whole application | A path by the same rule as path, inside the application's own path when it has one. / means the whole application. |
proxy.basic_auth[].username | string | required | At 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[].password | string | required | At least 8 characters and at most 72 bytes; no control characters. A secret: write it as a placeholder. |
proxy.redirects[].from | string | required | One path, matched exactly, by the same rule as path and inside the application's own path. Not /. Listed once. |
proxy.redirects[].to | string | required | A 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[].status | integer | 308 | One 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.
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 308A 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 anenvvalue:${ADMIN_PASSWORD}is filled in byshipwickfrom its environment or--env-file, else by the agent from the secrets stored withshipwick 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 samepathare several users of it. Where the paths of two entries overlap, the longer one decides: with one account for everything and another for/admin,/adminaccepts 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 unlesstohas 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.
| Type | integer |
| Default | 1 |
| Rule | 1 to 50. Must be 1 when volumes or publish is set. |
replicas: 2Replicas 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.
| Type | map of string to string |
| Default | none |
| Key rule | Letters, digits and underscores, not starting with a digit. Pattern: ^[A-Za-z_][A-Za-z0-9_]*$ |
| Value rule | Must not contain NUL bytes. |
env:
DATABASE_URL: postgres://app:${DATABASE_PASSWORD}@postgres:5432/app
LOG_LEVEL: infoValues 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.
| Field | Type | Rule | Healthy when |
|---|---|---|---|
health.path | string | Starts 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.tcp | integer | A container port, 1 to 65535. port is not needed. | A TCP connection to that port is accepted. |
health.command | list of strings | 1 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. |
| Field | Type | Default | Rule |
|---|---|---|---|
health.interval | duration | 10s | 1s to 5m |
health.timeout | duration | 3s | 100ms to 1m |
health.retries | integer | 3 | 1 to 100 |
health.start_period | duration | 0s | Up 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. |
port: 8080
health:
path: /health
interval: 10s
timeout: 3s
retries: 3health:
tcp: 5432health:
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, setstart_period: 1mrather than raisingretries, which would also make a running replica's failures take longer to notice. - Running. Every replica is probed every
interval. A replica that failsretriesprobes in a row is marked unhealthy, taken out of rotation and restarted, unlessrestart.policyisnever. A restarted replica getsstart_period + interval × retriesto 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.
| Field | Type | Default | Rule |
|---|---|---|---|
resources.cpu | number | unlimited | Cores, as a decimal number. 0.01 to 512. |
resources.memory | size | unlimited | A number and a unit, see Sizes. Minimum 6mb. |
resources:
cpu: 0.5
memory: 512mbMemory 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.
| Field | Type | Rule |
|---|---|---|
volumes[].name | string | Required. 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[].path | string | Required. 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.
name: postgres
image: postgres:17
port: 5432
replicas: 1
env:
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- name: data
path: /var/lib/postgresql/data
deploy:
strategy: recreateOn 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:
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: 1backups
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.
| Field | Type | Default | Rule |
|---|---|---|---|
backups.schedule | string | required when backups is present | Five cron fields, read in UTC, as for jobs. Runs of whitespace between fields are collapsed to one space. |
backups.keep | integer | 7 | 1 to 365. How many successful backups are kept; the oldest go once a new one has succeeded. |
backups.before | list of strings | none | A 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_timeout | duration | 1h | 1s to 24h. How long before may run. Requires backups.before. Since 0.6. |
backups.before_in | string | replica | replica or container: where before runs. Requires backups.before. Since 0.7. |
backups.stop | boolean | false | Stop 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.
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 falseTwo things decide whether what is in the archive can be trusted:
beforeruns 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 whatbefore_timeoutsays, 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: containerruns it where it can be ended.stop: truestops 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 | |
|---|---|
replica | The default. Inside the running replica, where a command that passes its limit stays until it ends by itself. |
container | In 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.
backups:
schedule: "0 3 * * *"
before: ["pg_dump", "-U", "postgres", "-h", "localhost", "-f", "/var/lib/postgresql/data/backup.sql", "app"]
before_timeout: 30m
before_in: containerOnly 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.
| Field | Type | Default | Rule |
|---|---|---|---|
publish[].port | integer | required | The port inside the container, 1 to 65535. |
publish[].host | integer | the same as port | The port on the server, 1 to 65535. Not 80 or 443: the proxy listens there. |
publish[].address | string | every address of the server | An 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[].protocol | string | tcp | tcp 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.
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: recreateNothing 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.
| Field | Type | Default | Rule |
|---|---|---|---|
logging.driver | string | required when logging is present | One of json-file, local, syslog, journald, gelf, fluentd, awslogs, splunk. Trimmed; case-sensitive. |
logging.options | map of string to string | none | At 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. |
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:portand nothing else: no user, path, query or fragment, and a port from 1 to 65535. The schemes are the driver's:syslog-addresstakesudp,tcportcp+tls;gelf-addresstakesudportcp;fluentd-addresstakestcportls.unix://andunixgram://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 thesplunkdriver. It is treated like anenvvalue — 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 withshipwick secret setlike anenvvalue 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.
| Field | Type | Default | Rule |
|---|---|---|---|
pre_deploy.command | list of strings | required when pre_deploy is present | 1 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.timeout | duration | 10m | 1s to 1h |
pre_deploy:
command: ["dotnet", "Migrate.dll"]
timeout: 10mIf 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.
| Field | Type | Default | Rule |
|---|---|---|---|
jobs[].name | string | required | Lowercase 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[].schedule | string | required | Five cron fields, read in UTC. Runs of whitespace between fields are collapsed to one space. |
jobs[].command | list of strings | required | 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. |
jobs[].timeout | duration | 1h | 1s to 24h |
At most 20 jobs per application.
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:
┌───────────── 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.
| Field | Type | Default | Rule |
|---|---|---|---|
restart.policy | string | always | One of always, on-failure, never |
| Value | Behavior |
|---|---|
always | Restart a replica that exited, whatever its exit code, and a running replica that turned unhealthy. |
on-failure | Restart 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. |
never | Never restart. |
restart:
policy: on-failureRestarts back off: 1s, 2s, 5s, 10s, 30s, then every 5 minutes.
deploy
| Field | Type | Default | Rule |
|---|---|---|---|
deploy.strategy | string | rolling | One of rolling, recreate. Must be recreate when volumes or publish is set. |
deploy.stop_timeout | duration | 10s | 1s to 10m. How long a replica that is being stopped gets between SIGTERM and SIGKILL. Does not apply to a static application. |
| Value | Behavior |
|---|---|
rolling | Replicas 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. |
recreate | The 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. |
deploy:
strategy: recreateWith 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.
deploy:
stop_timeout: 2m # WebSockets, long uploads: let them finishstop_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:
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_timeoutSince 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.
| Type | boolean |
| Required | no |
| Default | false |
| Rule | true or false. Does not apply to a static application. |
init: trueThe 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:
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_timeoutA 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.
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| Key | Default | |
|---|---|---|
read_only | false | true 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 |
capabilities | Docker's default set | none, 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_root | false | true 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,SETUIDandSYS_CHROOT. A name may be written in lower case and withCAP_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: noneand no key are different.nonekeeps nothing; without the key the containers keep Docker's default set. An empty list is refused rather than read as either.- A
tmpfspath is an absolute path inside the container, other than/, at which no volume and no other entry is mounted. non_rootis checked twice.shipwick validaterefusesuser: 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 deploysays 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.
| Unit | Bytes |
|---|---|
none, b | 1 |
k, kb, kib | 1024 |
m, mb, mib | 1024² |
g, gb, gib | 1024³ |
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:
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:
| Problem | Reported as |
|---|---|
| A required field is missing | name: / is required |
An image next to build | image: / is built here; remove image or build, expected build: . alone, or image: alone |
| A build path that is absolute or leaves the project | build.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 build | line 5: / unknown field "dockerfil". Since 0.10 |
build and static together | build: / cannot be combined with static: a static application has no image to build |
| A static application without a domain | domain: / is required for a static application: the proxy serves the files at it |
A container field next to static | port: / 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 project | static: / 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 folder | static.dir: / is required: the folder the fallback page is in, expected dist |
A fallback that is not a file in the folder | static.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 static | line 3: / unknown field "fallbak" |
A start_period out of range | health.start_period: / invalid value "2h": out of range, expected 30s, 1m, 5m, ... (up to 30m) |
| A reserved application name | name: / "caddy" is reserved for Shipwick's own services |
port missing while domain is set | port: / is required when domain is set |
port missing while health.path is set | port: / is required when health is set |
| Another application's built image | image: / 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 field | line 7: / unknown field "replica" |
| A value of the wrong YAML type | line 3: / cannot unmarshal … into a number |
entrypoint or command that is neither a string nor a list | line 3: / expected a string or a list of strings, not a map |
An empty entrypoint or command | command: / must not be empty; omit it to keep the image's own |
Too many arguments in entrypoint or command | command: / too many arguments (65), expected at most 64 |
| A newline or NUL byte in an argument | command[0]: / must not contain newlines or NUL bytes |
| An invalid user | user: / invalid value "App", expected a user name or id, with or without a group: app, 1000, 1000:1000 |
aliases or redirects without domain | aliases: / requires domain: aliases are served like it; redirects: / requires domain: redirects are sent to it |
| More than 20 aliases or redirects | aliases: / too many (21), expected at most 20 |
| An empty hostname | redirects[0]: / is empty, expected a hostname, e.g. www.example.com |
| A hostname with a scheme, port or path | aliases[0]: / invalid value "api.example.com/v1": not a valid hostname |
| A hostname listed twice | aliases[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 label | domain: / invalid value "*.*.example.com": a wildcard is one leading label and nothing else, expected api.example.com, *.example.com |
| A wildcard among the redirects | redirects[0]: / invalid value "*.example.com": not a valid hostname |
| Redirects next to a wildcard domain | redirects: / cannot be sent to a wildcard domain, expected domain: example.com, with the wildcard under aliases |
path without domain | path: / requires domain: a path is a part of it, expected domain: example.com |
An invalid path | path: / 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 domain | proxy: / requires domain: it says what the proxy does with the requests for it, expected domain: example.com |
An unknown key under proxy | line 12: / unknown field "header" |
strip_prefix without path | proxy.strip_prefix: / requires path: it is the prefix that is removed, expected path: /api |
| More than 50 headers | proxy.headers: / too many (51), expected at most 50 |
| An invalid header name | proxy.headers: / invalid header name "X Frame", expected letters, digits and dashes, e.g. X-Frame-Options |
| A header that belongs to the connection | proxy.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 case | proxy.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 value | proxy.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 accounts | proxy.basic_auth: / too many (21), expected at most 20 |
| An account's path outside the application's | proxy.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 one | proxy.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 path | proxy.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 password | proxy.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 redirects | proxy.redirects: / too many (101), expected at most 100 |
A redirect without from, or from everything | proxy.redirects[0].from: / is required; must be a path below /: redirecting everything would leave nothing to serve, expected /old |
| A path redirected twice | proxy.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:// URL | proxy.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 braces | proxy.redirects[0].to: / invalid value "/new page": must not contain whitespace, control characters, braces or backslashes |
| An unknown redirect status | proxy.redirects[0].status: / invalid value 303, expected 301, 302, 307, 308 |
| A redirect to itself | proxy.redirects[0].to: / redirects /old to itself, expected another path, or an https:// URL |
| Redirects that lead in a circle | proxy.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 range | health.interval: / invalid value "10m": out of range |
| An invalid environment variable name | env.my-var: / invalid variable name |
A health block without a kind | health: / one of path, tcp or command is required |
A health block with two kinds | health: / path and tcp are set; a health check is one of path, tcp or command |
A health.tcp port out of range | health.tcp: / invalid value 0, expected the port your application listens on, e.g. 5432 |
An empty or oversized health.command | health.command: / must not be empty; too many arguments (65), expected at most 64 |
An empty argument or a NUL byte in health.command | health.command[1]: / must not be empty; must not contain NUL bytes |
| An unknown deployment strategy | deploy.strategy: / invalid value "blue-green", expected rolling, recreate |
A stop_timeout out of range | deploy.stop_timeout: / invalid value "15m": out of range, expected 10s, 30s, 5m, ... (1s to 10m) |
An init that is not a boolean | line 3: / cannot unmarshal … into the expected type |
init next to static | init: / does not apply to a static application: the proxy serves the files, there is no container |
A key of security that does not exist | security: / expected read_only, tmpfs, capabilities, non_root |
| A capability outside Docker's default set | security.capabilities[0]: / invalid value "SYS_ADMIN": not in Docker's default set, and nothing is added to it |
| A capability listed twice | security.capabilities[1]: / "CHOWN" is listed twice |
| An empty list of capabilities | security.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 at | security.tmpfs[1].path: / "/data" is already mounted: … |
A tmpfs size outside 1 MB to 1 GB | security.tmpfs[0].size: / invalid value "2gb": out of range |
More than 10 tmpfs entries | security.tmpfs: / too many (11), expected at most 10 |
user: root, the id 0 or a name under non_root: true | user: / 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 volumes | volumes: / too many (11), expected at most 10 |
| A volume name used twice | volumes[1].name: / "data" is used twice |
| A volume path that is not absolute and clean | volumes[0].path: / invalid value "data/", expected an absolute path inside the container, e.g. /var/lib/postgresql/data |
| A volume path used twice | volumes[1].path: / "/data" is mounted twice |
Volumes without recreate | deploy.strategy: / must be "recreate" for an application with volumes: two versions cannot write the same files at once |
| Volumes with more than one replica | replicas: / must be 1 for an application with volumes, got 2: replicas cannot share a volume |
backups that is not a block | backups: / must be a block with a schedule |
An unknown key under backups | backups: / unknown field "schedul", expected schedule, keep, before, before_timeout, before_in, stop |
backups without a schedule | backups.schedule: / is required, expected "0 3 * * *" (minute hour day-of-month month day-of-week, in UTC) |
| An invalid backup schedule | backups.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 range | backups.keep: / invalid value 0, expected a number between 1 and 365 |
An empty or oversized before command | backups.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 before | backups.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 unit | backups.before_timeout: / invalid value "25h": out of range; invalid value "90", expected 10m, 1h, 6h, ... (1s to 24h) |
A before_in without before | backups.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 neither | backups.before_in: / invalid value "sidecar", with the same expectation |
"********" as an env value or a basic-auth password | env.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 volumes | backups: / needs volumes: a backup is an archive of the application's volumes |
Published ports without recreate | deploy.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 replica | replicas: / must be 1 for an application that publishes ports, got 2: replicas cannot share a server port |
| More than 20 published ports | publish: / too many (21), expected at most 20 |
A publish entry without port | publish[0].port: / is required, expected the port your application listens on, e.g. 5432 |
| A published port out of range | publish[0].port: / invalid value 70000; publish[0].host: / invalid value 0, expected a number between 1 and 65535 |
| A server port the proxy listens on | publish[0].host: / invalid value 80: the proxy listens there, expected another server port, e.g. 15432 |
| An unknown protocol | publish[0].protocol: / invalid value "sctp", expected tcp, udp |
| An address that is not an IP address | publish[0].address: / invalid value "db.internal", expected an address of the server, e.g. 10.0.0.5 |
| A server port published twice | publish[1].host: / server port 5432/tcp is published twice, expected a different server port for each entry |
logging without a driver | logging.driver: / is required when logging is set, expected json-file, local, syslog, journald, gelf, fluentd, awslogs, splunk |
| An unknown logging driver | logging.driver: / invalid value "GELF" |
| More than 20 logging options | logging.options: / too many (21), expected at most 20 |
| An invalid option name | logging.options.Gelf-Address: / invalid option name, expected lowercase letters, digits and dashes, e.g. gelf-address |
| An option that names a file on the server | logging.options.syslog-tls-ca-cert: / names a file on the server, which Shipwick never reads |
| An option value too long | logging.options.tag: / value is too long (1025 characters), expected at most 1024 |
| A newline or NUL byte in an option value | logging.options.tag: / value must not contain newlines or NUL bytes |
| A collector address without a scheme or port | logging.options.gelf-address: / invalid value "logs.example.com:12201": must be scheme://host:port |
| A collector address that is a socket | logging.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 speak | logging.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 credentials | logging.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 port | logging.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 command | pre_deploy.command: / is required, expected ["dotnet", "Migrate.dll"] |
| A command with too many or oversized arguments | pre_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 range | pre_deploy.timeout: / invalid value "2h": out of range, expected 30s, 10m, 1h, ... (1s to 1h) |
| More than 20 jobs | jobs: / too many (21), expected at most 20 |
| A job without a name | jobs[0].name: / is required, expected nightly-report |
| An invalid job name | jobs[0].name: / invalid value "Nightly", expected lowercase letters, digits and dashes, e.g. nightly-report (max 40 characters) |
| A reserved job name | jobs[0].name: / "run" is reserved, expected another name, e.g. nightly-report |
| A job name used twice | jobs[1].name: / "cleanup" is used twice, expected a different name for each job |
| A job without a schedule | jobs[0].schedule: / is required, expected "0 3 * * *" (minute hour day-of-month month day-of-week, in UTC) |
| An invalid schedule | jobs[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 command | jobs[0].command: / is required, expected ["node", "report.js"] |
| A job timeout out of range | jobs[0].timeout: / invalid value "25h": out of range, expected 5m, 1h, 12h, ... (1s to 24h) |
| An empty file | deploy.yaml: / file is empty |
| Several YAML documents in one file | deploy.yaml: / multiple YAML documents are not supported; describe one application per file |
| A file over 64 KB | deploy.yaml: / file is too large (max 64 KB) |
| A hostname in use, refused by the agent | domain: / 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 agent | path: / 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 agent | aliases[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 agent | proxy.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 agent | publish[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:
{
"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
# 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.
# 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]apps | Required, 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 entry | A 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. |
after | A 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.