diff --git a/lib/kamal/cli/templates/deploy.yml b/lib/kamal/cli/templates/deploy.yml index 89c7a7c3f..e79c9d597 100644 --- a/lib/kamal/cli/templates/deploy.yml +++ b/lib/kamal/cli/templates/deploy.yml @@ -1,101 +1,203 @@ -# Name of your application. Used to uniquely configure containers. -service: my-app - -# Name of the container image. -image: my-user/my-app +# This YAML file is used by Kamal to configure its deployment of this web-app to one or more servers. +# Kamal builds a Docker image of the app itself via a Dockerfile and a local clone of the app-code repository +# (changes don't need to be first pushed to any remote), then pushes this image to the image repository +# configured here. Kamal then deploys the web-app image it built to the list of servers given here. +# Kamal can also deploy optional accessory images configured here (such as a database), +# plus an optional Kamal-Proxy container to act as the single web listener and optional single SSL (https) +# processor and certificate manager, which then transfers unencrypted HTTP to and from the web-app containers. +# +# This file is similar to a Docker Compose YAML file, but does not currently support interpolation of +# environment variables. YAML anchors (&anchor) and aliases (*anchor) are however available to reduce +# duplication, although aliases must substitute for a whole config value rather than a sub-string of such. +# +# All available configuration settings beyond those in this example are described at +# https://kamal-deploy.org/docs/configuration/overview/ -# Deploy to these servers. -servers: - web: - - 192.168.0.1 - # job: - # hosts: - # - 192.168.0.1 - # cmd: bin/jobs -# Enable SSL auto certification via Let's Encrypt and allow for multiple apps on a single web server. -# Remove this section when using multiple web servers and ensure you terminate SSL at your load balancer. +# The name of your application. +# This is only directly used to uniquely prefix the name of the web-app image/container +# and its accessory containers. # -# Note: If using Cloudflare, set encryption mode in SSL/TLS setting to "Full" to enable CF-to-app encryption. -proxy: - ssl: true - host: app.example.com - # Proxy connects to your container on port 80 by default. - # app_port: 3000 +service: my-app &service -# Credentials for your image host. -registry: - # Specify the registry server, if you're not using Docker Hub - # server: registry.digitalocean.com / ghcr.io / ... - username: my-user - # Always use an access token rather than real password (pulled from .kamal/secrets). - password: - - KAMAL_REGISTRY_PASSWORD - -# Configure builder setup. +# Configure the web-app container builder. By default, building is done on the local machine, +# but remote building is supported. +# +# See https://kamal-deploy.org/docs/configuration/builder-examples/ for more information. +# builder: + # The CPU architecture of the server to which the app is being deployed. Emulation allows it to be + # different to the architecture of the build host. arch: amd64 + # Pass in additional build args needed for your Dockerfile. - # args: - # RUBY_VERSION: <%= ENV["RBENV_VERSION"] || ENV["rvm_ruby_string"] || "#{RUBY_ENGINE}-#{RUBY_ENGINE_VERSION}" %> + #args: + # RUBY_VERSION: <%= ENV["RBENV_VERSION"] || ENV["rvm_ruby_string"] || "#{RUBY_ENGINE}-#{RUBY_ENGINE_VERSION}" %> -# Inject ENV variables into containers (secrets come from .kamal/secrets). + +# Inject environment variables into the web-app container. +# Secret variables are the names of variables set in .kamal/secrets. +# Both clear and secret variables are made available to any erb-file parsed during app start-up. +# +#env: +# clear: +# DB_USER: *service +# DB_NAME_PREFIX: *service +# +# # A web-app DB_HOST variable (or a variable with a different name) could be set here to the name of the +# # database accessory container, which by default is the service name set above, hyphenated with the +# # database accessory YAML key set below (e.g. my-app-db or my-app-postgres). +# # If such a variable setting is used by the web-app, the app and the database containers will communicate +# # through the Docker private-IP network, and there is no need to expose the database to either +# # the host or the world by setting its accessory port below. +# # Alternatively, this variable can be set to an IP address or hostname. +# # Or instead of using a variable, the database hostname can be set directly in the web-app. +# DB_HOST: my-app-db # -# env: -# clear: -# DB_HOST: 192.168.0.2 -# secret: -# - RAILS_MASTER_KEY +# secret: +# - DB_USER_PASSWORD +# - RAILS_MASTER_KEY -# Aliases are triggered with "bin/kamal ". You can overwrite arguments on invocation: -# "bin/kamal app logs -r job" will tail logs from the first server in the job section. + +# Map one or more persistent storage volumes between a web-app container path and the host filesystem. +# The host filesytem path before the colon can either be an absolute path or a volume identifier, +# the latter form being mapped to the /var/lib/docker/volumes//_data host path. # -# aliases: -# shell: app exec --interactive --reuse "bash" +#volumes: +# - "app_storage:/app/storage" + -# Use a different ssh user than root +# Bridge fingerprinted assets, like JS and CSS, between versions to avoid +# hitting 404 on in-flight requests. Combines all files from the new and old +# versions inside the asset_path. # -# ssh: -# user: app +#asset_path: /app/public/assets + -# Use a persistent storage volume. +# The registry that will host the built web-app Docker image. # -# volumes: -# - "app_storage:/app/storage" +registry: + # Specify the hostname of the registry, only necessary if not Docker Hub. + #server: registry.digitalocean.com / ghcr.io / my-harbor-hostname[:port] / ... -# Bridge fingerprinted assets, like JS and CSS, between versions to avoid -# hitting 404 on in-flight requests. Combines all files from new and old -# version inside the asset_path. + username: my-registry-username + + # The name of the environment variable that holds the password for the above registry username, + # as set in .kamal/secrets. If supported by your registry, it's safer to use an access token + # rather than a password. + password: + - KAMAL_REGISTRY_PASSWORD + + +# The name of the web-app container image. +# If a third-party container image registry is being used (as configured above), this is usually of the form +# /. For the self-hosted Harbor registry, this will instead +# be /. The second part of this value will usually be automatically created, +# and so could be named after the service above. # -# asset_path: /app/public/assets +image: my-user/my-app -# Configure rolling deploys by setting a wait time between batches of restarts. + +# Use a different ssh user than root on the server to which you are deploying. +# +#ssh: +# user: app + + +# Deploy to the servers with the given IP addresses or hostnames. ssh must be able to connect to +# the given addresss or hostname with the user set above through a server-deployed private key and a +# local ssh Host config section for the given address or hostname. +# +servers: + web: + - &web-server + # job: + # hosts: + # - *web-server + # cmd: bin/jobs + + +# Add one or more accessory services. +# +#accessories: +# db: +# # The Docker Hub tagged public image for this accessory. +# # Another registry can instead be used: see https://kamal-deploy.org/docs/configuration/accessories/ +# image: mysql:8.0 +# +# # The public address or hostname where this accessory should be deployed. +# host: *web-server # -# boot: -# limit: 10 # Can also specify as a percentage of total hosts, such as "25%" -# wait: 2 - -# Use accessory services (secrets come from .kamal/secrets). -# -# accessories: -# db: -# image: mysql:8.0 -# host: 192.168.0.2 -# port: 3306 -# env: -# clear: -# MYSQL_ROOT_HOST: '%' -# secret: -# - MYSQL_ROOT_PASSWORD +# # The port that will be opened and published for this accessory. +# # If not set, no port will be opened nor published. +# # A setting of "::" will expose the accessory to the given +# # external IP and port. For example, "127.0.0.1:3306:3306" will only expose the accessory to the host. +# # A numeric-only setting is equivalent to "0.0.0.0::", exposing the accessory to all +# # IP addresses unless blocked by another firewall. +# # Whatever the setting, communication is available on the Docker private IP network via the accessory +# # container name - (my-app-db in this example). +# port: 3306 +# +# # The web-app environment variables above are not propagated to accessories. +# env: +# clear: +# MYSQL_ROOT_HOST: '%' +# # As set in .kamal/secrets. +# secret: +# - MYSQL_ROOT_PASSWORD +# +# # List any files from the dev repository that you wish copied into a path of this accessory container +# # for initialization, etc. The format is :. +# # Such a file can be an erb file that will be parsed using only the clear environment +# # variables defined above. Secret variables are however made available to script files. # files: # - config/mysql/production.cnf:/etc/mysql/my.cnf # - db/production.sql:/docker-entrypoint-initdb.d/setup.sql +# +# # Link host directories with accessory container absolute paths to persist data across accessory +# # container lifetimes. Host directories are created if absent. # directories: +# # If not an absolute path, the key part of the value below uses the host directory +# # ~// # - data:/var/lib/mysql -# redis: -# image: valkey/valkey:8 -# host: 192.168.0.2 -# port: 6379 -# directories: -# - data:/data +# +# redis: +# image: valkey/valkey:8 +# host: *web-server +# port: 6379 +# directories: +# - data:/data + + +# Configure the Kamal Proxy container, which supports both name-based virtual servers, +# by routing hostnames to web-apps, and encryption/decryption for the https protocol, +# including automatically-updated TLS certificates. The proxy will either be deployed to the first +# listed web-server or no websevvers ("proxy: false"). Ensure you terminate SSL at your load balancer. +# +proxy: + # If this host field is absent the proxy will route all hostnames to this web-app; + # a string will route a single name; or a YAML array of hostnames can be routed. + # These routes will be added to a proxy that is already routing other web-apps. + host: app.example.com + + # Setting this "true" enables both https processing and auto-certification via Let's Encrypt of all listed hostnames. + # If using Cloudflare, set the encryption mode in its SSL/TLS setting to "Full" to enable CF-to-app encryption. + ssl: true + + # The proxy connects to web-app containers on port 80 by default. + #app_port: 3000 + + +# Configure rolling deploys by setting a wait time between batches of restarts. +# +#boot: +# limit: 10 # Can also specify as a percentage of total hosts, such as "25%" +# wait: 2 + + +# Aliases are triggered with "bin/kamal ". You can overwrite arguments on invocation: +# "bin/kamal app logs -r job" will tail logs from the first server in the job section. +# +#aliases: +# shell: app exec --interactive --reuse "bash"