Step 1: Configure Kamal
Overview
- configure
config/deploy.yml
You've gathered your ingredients; now it's time to start cooking. Much of the data you have gathered gets deposited into two files.
If you are using Rails 8, you already have Kamal installed. If not, you can install it with gem install kamal
.
Installation instructions
Once installed, you can create your configuration files by running kamal init
.
First up: config/deploy.yml
. Note that there will be minor differences in the initial content of this file depending on whether you created it using kamal init
or rails new
, as Rails will pre-fill a number of these fields.
Kamal provides full documentation on this file. Configuration Overview The fields you will be updating are highlighted below:
config/deploy.yml | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 |
|
- service is the container name prefix. Use whatever you want here.
- image the desired name of the image in the docker registry. Built images will be pushed to this name, and Kamal will pull this named image to the target host(s) upon deploy.
- You put the IP address of your host in this file twice: once as the deployment target, and once as your builder.
- You also put the IP address of your host here.
- You put your domain name in the proxy section; HTTPS certificates will be provided for you using Let's Encrypt.
- In the registry section, you select your container registry server, which defaults to Docker Hub. You then provide the username and password needed to access that container registry server. The password secret should always be an access token provided by
.kamal/secrets
. - The default for building is to use your last git commit. Initially, it is sometimes easier to deploy the files as they exist on your development machine until things are working; that's what
context: .
does. This does mean that at times you will deploy changes and not commit them; for this reason, it is recommended that you delete this line once you are comfortable with your setup. - The remainder of the builder section specifies to do remote builds on your deployment machine. If you have a separate builder, you can specify that here.
- In the secret section, you list your S3 secrets. Alternatively, they can be placed in your
credentials file.
Some of these values (examples:
ENDPOINT_ID
,REGION
, andBUCKET_NAME
) could be passed in the clear instead. - While not related to data you've captured, aliases are useful for commands that you are likely to repeat.
- Uncomment these lines. Volume is used to retain your data across deployments: it maps a directory in your container to a directory on your host machine. We're not changing it, but note the recommendation in the comment above it to back this directory up off-server is very important.
- For logging, you can keep the default (
json-file
), or go with Docker's recommendation (local
). Docker Logging Configuration Either way, you likely will want to adjustmax-size
and/ormax-file
.
While this was a fair amount of configuration, the prep work you did before you got to this point made it quick work.
For the most part, this configuration is a set-and-forget operation. It is rare that you will need to update this file again.