spacebar/kamal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README to match new exec approach

Browse Source
This commit is contained in:
David Heinemeier Hansson
2023-01-14 12:09:09 +01:00
parent 94b3cfd0f4
commit e78da2a925
1 changed files with 32 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
README.md
View File

@@ -1,10 +1,10 @@
# MRSK
MRSK ships zero-downtime deploys of Rails apps packed as containers to any host. It uses the dynamic reverse-proxy Traefik to hold requests while the new application container is started and the old one is wound down. It works seamlessly across multiple hosts, using SSHKit to execute commands.
MRSK deploys Rails apps packed as containers to any host with zero downtime. It uses the dynamic reverse-proxy Traefik to hold requests while the new application container is started and the old one is wound down. It works seamlessly across multiple hosts, using SSHKit to execute commands.
## Installation
Add the gem with `bundle add mrsk`, then run `rake mrsk:init`, and then edit the new file in `config/deploy.yml`. It could look as simple as this:
Install MRSK globally with `gem install mrsk`. Then inside your app directory, you run `mrsk install`. Now edit the new file in `config/deploy.yml`. It could look as simple as this:
```yaml
service: hey
@@ -13,34 +13,27 @@ servers:
- 192.168.0.1
- 192.168.0.2
registry:
username: <%= Rails.application.credentials.registry["username"] %>
password: <%= Rails.application.credentials.registry["password"] %>
```
Then ensure your encrypted credentials have the registry username + password by editing them with `rails credentials:edit`:
```
registry:
username: real-user-name
password: real-registry-password-or-token
username: registry-user-name
password: registry-user-password-needs-more-secure-option
```
Now you're ready to deploy a multi-arch image to the servers:
```
./bin/mrsk deploy
mrsk deploy
```
This will:
1. Log into the registry both locally and remotely
2. Build the image using the standard Dockerfile in the root of the application.
3. Push the image to the registry.
4. Pull the image from the registry on the servers.
5. Ensure Traefik is running and accepting traffic on port 80.
6. Stop any containers running a previous versions of the app.
7. Start a new container with the version of the app that matches the current git version hash.
8. Prune unused images and stopped containers to ensure servers don't fill up.
1. Install Docker on any remote server that might be missing it (using apt-get)
2. Log into the registry both locally and remotely
3. Build the image using the standard Dockerfile in the root of the application.
4. Push the image to the registry.
5. Pull the image from the registry on the servers.
6. Ensure Traefik is running and accepting traffic on port 80.
7. Stop any containers running a previous versions of the app.
8. Start a new container with the version of the app that matches the current git version hash.
9. Prune unused images and stopped containers to ensure servers don't fill up.
Voila! All the servers are now serving the app on port 80. If you're just running a single server, you're ready to go. If you're running multiple servers, you need to put a load balancer in front of them.
@@ -53,8 +46,8 @@ The default registry for Docker is Docker Hub. If you'd like to use a different
```yaml
registry:
server: registry.digitalocean.com
username: <%= Rails.application.credentials.registry["username"] %>
password: <%= Rails.application.credentials.registry["password"] %>
username: registry-user-name
password: registry-user-password-needs-more-secure-option
```
### Using a different SSH user than root
@@ -141,7 +134,7 @@ builder:
Note: You must have Docker running on the remote host being used as a builder.
With that configuration in place, you can setup the local/remote configuration using `./bin/mrsk build:remote:create`. If you wish to remove the contexts and buildx instances again, you can run `./bin/mrsk build:remote:remove`. If you had already built using the standard emulation setup, run `./bin/mrsk build:remove` before doing `./bin/mrsk build:remote:create`.
With that configuration in place, you can setup the local/remote configuration using `mrsk build create`. If you wish to remove the contexts and buildx instances again, you can run `mrsk build remove`. If you had already built using the standard emulation setup, run `mrsk build remove` before doing `mrsk build remote`.
### Configuring native builder when multi-arch isn't needed
@@ -156,11 +149,11 @@ builder:
### Remote execution
If you need to execute commands inside the Rails containers, you can use `./bin/mrsk app:exec`, `./bin/mrsk app:exec:once`, `./bin/mrsk app:exec:rails`, and `./bin/mrsk app:exec:once:rails`. Examples:
If you need to execute commands inside the Rails containers, you can use `mrsk app exec`, `mrsk app exec --once`, `mrsk app runner`, and `mrsk app runner --once`. Examples:
```bash
# Runs command on all servers
./bin/mrsk app:exec CMD='ruby -v'
mrsk app exec 'ruby -v'
App Host: xxx.xxx.xxx.xxx
ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [x86_64-linux]
@@ -168,11 +161,11 @@ App Host: xxx.xxx.xxx.xxx
ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [x86_64-linux]
# Runs command on first server
./bin/mrsk app:exec:once CMD='cat .ruby-version'
mrsk app exec --once 'cat .ruby-version'
3.1.3
# Runs Rails command on all servers
./bin/mrsk app:exec:rails CMD=about
mrsk app exec 'bin/rails about'
App Host: xxx.xxx.xxx.xxx
About your application's environment
Rails version 7.1.0.alpha
@@ -197,19 +190,18 @@ Environment production
Database adapter sqlite3
Database schema version 20221231233303
# Runs Rails command on first server
./bin/mrsk app:exec:once:rails CMD='db:version'
database: storage/production.sqlite3
Current version: 20221231233303
# Runs Rails runner on first server
mrsk app runner 'puts Rails.application.config.time_zone'
UTC
```
### Running a Rails console on the primary host
If you need to interact with the production console for the app, you can use `./bin/mrsk app:console`, which will start a Rails console session on the primary host. Be mindful that this is a live wire! Any changes made to the production database will take effect immeditately.
If you need to interact with the production console for the app, you can use `mrsk app console`, which will start a Rails console session on the primary host. You can start the console on a different host using `mrsk app console --host 192.168.0.2`. Be mindful that this is a live wire! Any changes made to the production database will take effect immeditately.
### Inspecting
You can see the state of your servers by running `./bin/mrsk info`. It'll show something like this:
You can see the state of your servers by running `mrsk details`. It'll show something like this:
```
Traefik Host: xxx.xxx.xxx.xxx
@@ -229,11 +221,11 @@ CONTAINER ID IMAGE
1d3c91ed1f55 registry.digitalocean.com/user/app:6ef8a6a84c525b123c5245345a8483f86d05a123 "/rails/bin/docker-e…" 13 minutes ago Up 13 minutes 3000/tcp chat-6ef8a6a84c525b123c5245345a8483f86d05a123
```
You can also see just info for app containers with `./bin/mrsk app:info` or just for Traefik with `./bin/mrsk traefik:info`.
You can also see just info for app containers with `mrsk app details` or just for Traefik with `mrsk traefik details`.
### Rollback
If you've discovered a bad deploy, you can quickly rollback by reactivating the old, paused container image. You can see what old containers are available for rollback by running `./bin/mrsk app:containers`. It'll give you a presentation similar to `./bin/mrsk app:info`, but include all the old containers as well. Showing something like this:
If you've discovered a bad deploy, you can quickly rollback by reactivating the old, paused container image. You can see what old containers are available for rollback by running `mrsk app containers`. It'll give you a presentation similar to `mrsk app details`, but include all the old containers as well. Showing something like this:
```
App Host: 164.92.105.119
@@ -247,20 +239,17 @@ badb1aa51db4 registry.digitalocean.com/user/app:6ef8a6a84c525b123c5245345a8483
6f170d1172ae registry.digitalocean.com/user/app:e5d9d7c2b898289dfbc5f7f1334140d984eedae4 "/rails/bin/docker-e…" 31 minutes ago Exited (1) 27 minutes ago chat-e5d9d7c2b898289dfbc5f7f1334140d984eedae4
```
From the example above, we can see that `e5d9d7c2b898289dfbc5f7f1334140d984eedae4` was the last version, so it's available as a rollback target. We can perform this rollback by running `./bin/mrsk rollback VERSION=e5d9d7c2b898289dfbc5f7f1334140d984eedae4`. That'll stop `6ef8a6a84c525b123c5245345a8483f86d05a123` and then start `e5d9d7c2b898289dfbc5f7f1334140d984eedae4`. Because the old container is still available, this is very quick. Nothing to download from the registry.
From the example above, we can see that `e5d9d7c2b898289dfbc5f7f1334140d984eedae4` was the last version, so it's available as a rollback target. We can perform this rollback by running `mrsk rollback e5d9d7c2b898289dfbc5f7f1334140d984eedae4`. That'll stop `6ef8a6a84c525b123c5245345a8483f86d05a123` and then start `e5d9d7c2b898289dfbc5f7f1334140d984eedae4`. Because the old container is still available, this is very quick. Nothing to download from the registry.
Note that by default old containers are pruned after 3 days when you run `./bin/mrsk deploy`.
Note that by default old containers are pruned after 3 days when you run `mrsk deploy`.
### Removing
If you wish to remove the entire application, including Traefik, containers, images, and registry session, you can run `./bin/mrsk remove`. This will leave the servers clean.
If you wish to remove the entire application, including Traefik, containers, images, and registry session, you can run `mrsk remove`. This will leave the servers clean.
## Stage of development
This is alpha software. Lots of stuff is missing. Here are some of the areas we seek to improve:
- Adapterize commands to work with Podman and other container runners
- Integrate with cloud CI pipelines
This is alpha software. Lots of stuff is missing. Lots of stuff will keep moving around for a while.
## License