diff --git a/README.md b/README.md index a201e372..a71c360d 100644 --- a/README.md +++ b/README.md @@ -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