mrsk 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e1765484e15fa40e1f8af291f09fc56e29a00a2b6e4aba3f30dda44d3982074
-  data.tar.gz: 302d1eb25ac51ce8f8e2fcfe187863b7ba5caa8b3b55ba7b806d20b7bf7cab7a
+  metadata.gz: d8f3425abee6c013a917d960080160e02009976a7980bcf094bad847eb62631a
+  data.tar.gz: 153d6c0c396545ce451ac41470de8c325438331c05c0927c93f41d634f039c0d
 SHA512:
-  metadata.gz: 9760a98b211d8809102fb8bdc006690ad4242342aae5510c3f7cb632e86f572cc78f9b09203bc25fa4035b3862872d1f3b4063b8ea8c8efaa03a7ef9497481c0
-  data.tar.gz: ef77a4d3ddefb4e08542e623f9a3be18e86b4d532456a53416eace6dc815b2149acb4797814f0d8210948b096150881428f676af667117e465d53ac438da8f47
+  metadata.gz: e4de84f5283ee1dde444b9a2107e9d67ae7229d1c8ddc1b89679767ea8a5ba1568ace8f4f144712ceefcff15d7c85acbcd43079225b741d4b551c40aed55a7a4
+  data.tar.gz: b8bfca36906d4b6cfe3f1b332ed9fae1bd6077a10d4388a449a12bb5f308267681700b31d8d89a08a99fa784054f03167d4f776816b6aaff29ec5216bb7e5287

data/README.md

@@ -4,9 +4,23 @@ MRSK deploys web apps anywhere from bare metal to cloud VMs using Docker with ze
 
 Watch the screencast: https://www.youtube.com/watch?v=LL1cV2FXZ5I
 
+Join us on Discord: https://discord.gg/YgHVT7GCXS
+
 ## Installation
 
-Install MRSK globally with `gem install mrsk`. Then, inside your app directory, run `mrsk init` (or `mrsk init --bundle` within Rails apps where you want a bin/mrsk binstub). Now edit the new file `config/deploy.yml`. It could look as simple as this:
+If you have a Ruby environment available, you can install MRSK globally with:
+
+```sh
+gem install mrsk
+```
+
+...otherwise, you can run a dockerized version via an alias (add this to your ${SHELL}rc to simplify re-use):
+
+```sh
+alias mrsk='docker run --rm -it -v $HOME/.ssh:/root/.ssh -v /var/run/docker.sock:/var/run/docker.sock -v ${PWD}/:/workdir  ghcr.io/mrsked/mrsk'
+```
+
+Then, inside your app directory, run `mrsk init` (or `mrsk init --bundle` within Rails apps where you want a bin/mrsk binstub). Now edit the new file `config/deploy.yml`. It could look as simple as this:
 
 ```yaml
 service: hey
@@ -23,7 +37,7 @@ env:
     - RAILS_MASTER_KEY
 ```
 
-Then edit your `.env` file to add your registry password as `MRSK_REGISTRY_PASSWORD` (and your `RAILS_MASTER_KEY` for production with a Rails app). 
+Then edit your `.env` file to add your registry password as `MRSK_REGISTRY_PASSWORD` (and your `RAILS_MASTER_KEY` for production with a Rails app).
 
 Now you're ready to deploy to the servers:
 
@@ -34,7 +48,7 @@ mrsk deploy
 This will:
 
 1. Connect to the servers over SSH (using root by default, authenticated by your ssh key)
-2. Install Docker on any server that might be missing it (using apt-get)
+2. Install Docker on any server that might be missing it (using apt-get): root access is needed via ssh for this.
 3. Log into the registry both locally and remotely
 4. Build the image using the standard Dockerfile in the root of the application.
 5. Push the image to the registry.
@@ -67,6 +81,16 @@ Docker Swarm is much simpler than Kubernetes, but it's still built on the same d
 
 Ultimately, there are a myriad of ways to deploy web apps, but this is the toolkit we're using at [37signals](https://37signals.com) to bring [HEY](https://www.hey.com) [home from the cloud](https://world.hey.com/dhh/why-we-re-leaving-the-cloud-654b47e0) without losing the advantages of modern containerization tooling.
 
+## Running MRSK from Docker
+
+MRSK is packaged up in a Docker container similarly to [rails/docked](https://github.com/rails/docked). This will allow you to run MRSK (from your application directory) without having to install any dependencies other than Docker. Add the following alias to your profile configuration to make working with the container more convenient:
+
+```bash
+alias mrsk="docker run -it --rm -v '${PWD}:/workdir' -v '${SSH_AUTH_SOCK}:/ssh-agent' -v /var/run/docker.sock:/var/run/docker.sock -e 'SSH_AUTH_SOCK=/ssh-agent' ghcr.io/mrsked/mrsk:latest"
+```
+
+Since MRSK uses SSH to establish a remote connection, it will need access to your SSH agent. The above command uses a volume mount to make it available inside the container and configures the SSH agent inside the container to make use of it.
+
 ## Configuration
 
 ### Using .env file to load required environment variables
@@ -99,9 +123,9 @@ If you need separate env variables for different destinations, you can set them
 
 #### Bitwarden as a secret store
 
-If you are using open source secret store like bitwarden, you can create `.env.erb` as a template which looks up the secrets. 
+If you are using open source secret store like bitwarden, you can create `.env.erb` as a template which looks up the secrets.
 
-You can store `SOME_SECRET` in a secure note in bitwarden vault. 
+You can store `SOME_SECRET` in a secure note in bitwarden vault.
 
 ```
 $ bw list items --search SOME_SECRET | jq
@@ -140,7 +164,7 @@ SOME_SECRET=<%= `bw get notes 123123123-1232-4224-222f-234234234234 --session #{
 <% else raise ArgumentError, "session_token token missing" end %>
 ```
 
-Then everyone deploying the app can run `mrsk envify` and mrsk will generate `.env` 
+Then everyone deploying the app can run `mrsk envify` and mrsk will generate `.env`
 
 
 ### Using another registry than Docker Hub
@@ -150,9 +174,9 @@ The default registry is Docker Hub, but you can change it using `registry/server
 ```yaml
 registry:
   server: registry.digitalocean.com
-  username:  
+  username:
     - DOCKER_REGISTRY_TOKEN
-  password: 
+  password:
     - DOCKER_REGISTRY_TOKEN
 ```
 
@@ -222,6 +246,12 @@ volumes:
   - "/local/path:/container/path"
 ```
 
+### MRSK env variables
+
+The following env variables are set when your container runs:
+
+`MRSK_CONTAINER_NAME` : this contains the current container name and version
+
 ### Using different roles for servers
 
 If your application uses separate hosts for running jobs or other roles beyond the default web running, you can specify these hosts in a dedicated role with a new entrypoint command like so:
@@ -256,12 +286,12 @@ servers:
 
 You can specialize the default Traefik rules by setting labels on the containers that are being started:
 
-```
+```yaml
 labels:
-  traefik.http.routers.hey.rule: Host(\`app.hey.com\`)
+  traefik.http.routers.hey.rule: Host(`app.hey.com`)
 ```
 
-Note: The escaped backticks are needed to ensure the rule is passed in correctly and not treated as command substitution by Bash!
+Note: The backticks are needed to ensure the rule is passed in correctly and not treated as command substitution by Bash!
 
 This allows you to run multiple applications on the same server sharing the same Traefik instance and port.
 See https://doc.traefik.io/traefik/routing/routers/#rule for a full list of available routing rules.
@@ -303,6 +333,29 @@ servers:
 
 That'll start the job containers with `docker run ... --cap-add --cpu-count 4 ...`.
 
+### Configuring logging
+
+You can configure the logging driver and options passed to Docker using `logging`:
+
+```yaml
+logging:
+  driver: awslogs
+  options:
+    awslogs-region: "eu-central-2"
+    awslogs-group: "my-app"
+```
+
+If nothing is configured, the default option `max-size=10m` is used for all containers. The default logging driver of Docker is `json-file`.
+
+### Using a different stop wait time
+
+On a new deploy, each old running container is gracefully shut down with a `SIGTERM`, and after a grace period of `10` seconds a `SIGKILL` is sent.
+You can configure this value via the `stop_wait_time` option:
+
+```yaml
+stop_wait_time: 30
+```
+
 ### Using remote builder for native multi-arch
 
 If you're developing on ARM64 (like Apple Silicon), but you want to deploy on AMD64 (x86 64-bit), you can use multi-architecture images. By default, MRSK will setup a local buildx configuration that does this through QEMU emulation. But this can be quite slow, especially on the first build.
@@ -408,6 +461,46 @@ traefik:
   host_port: 8080
 ```
 
+### Configure docker options for traefik
+
+We allow users to pass additional docker options to the trafik container like
+
+```yaml
+traefik:
+  options:
+    publish:
+    - 8080:8080
+    volumes:
+    - /tmp/example.json:/tmp/example.json
+    memory: 512m
+```
+
+This will start the traefik container with a command like: `docker run ... --volume /tmp/example.json:/tmp/example.json --publish 8080:8080 `
+
+
+### Configure alternate entrypoints for traefik
+
+You can configure multiple entrypoints for traefik like so:
+
+```yaml
+service: myservice
+
+labels:
+  traefik.tcp.routers.other.rule: 'HostSNI(`*`)'
+  traefik.tcp.routers.other.entrypoints: otherentrypoint
+  traefik.tcp.services.other.loadbalancer.server.port: 9000
+  traefik.http.routers.myservice.entrypoints: web
+  traefik.http.services.myservice.loadbalancer.server.port: 8080
+
+traefik:
+  options:
+    publish:
+      - 9000:9000
+  args:
+    entrypoints.web.address: ':80'
+    entrypoints.otherentrypoint.address: ':9000'
+```
+
 ### Configuring build args for new images
 
 Build arguments that aren't secret can also be configured:
@@ -427,7 +520,7 @@ FROM ruby:$RUBY_VERSION-slim as base
 
 ### Using accessories for database, cache, search services
 
-You can manage your accessory services via MRSK as well. The services will build off public images, and will not be automatically updated when you deploy:
+You can manage your accessory services via MRSK as well. Accessories are long-lived services that your app depends on. They are not updated when you deploy.
 
 ```yaml
 accessories:
@@ -442,16 +535,44 @@ accessories:
         - MYSQL_ROOT_PASSWORD
     volumes:
       - /var/lib/mysql:/var/lib/mysql
+    options:
+      cpus: 4
+      memory: "2GB"
   redis:
     image: redis:latest
-    host: 1.1.1.4
+    role:
+      - web
     port: "36379:6379"
     volumes:
       - /var/lib/redis:/data
+  internal-example:
+    image: registry.digitalocean.com/user/otherservice:latest
+    host: 1.1.1.5
+    port: 44444
+```
+
+The hosts that the accessories will run on can be specified by hosts or roles:
+
+```yaml
+  # Single host
+  mysql:
+    host: 1.1.1.1
+  # Multiple hosts
+  redis:
+    hosts:
+      - 1.1.1.1
+      - 1.1.1.2
+  # By role
+  monitoring:
+    roles:
+      - web
+      - jobs
 ```
 
 Now run `mrsk accessory start mysql` to start the MySQL server on 1.1.1.3. See `mrsk accessory` for all the commands possible.
 
+Accessory images must be public or tagged in your private registry.
+
 ### Using Cron
 
 You can use a specific container to run your Cron jobs:
@@ -616,6 +737,30 @@ Note that by default old containers are pruned after 3 days when you run `mrsk d
 
 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.
 
+## Locking
+
+Commands that are unsafe to run concurrently will take a deploy lock while they run. The lock is the `mrsk_lock` directory on the primary server.
+
+You can check the lock status with:
+
+```
+mrsk lock status
+
+Locked by: AN Other at 2023-03-24 09:49:03 UTC
+Version: 77f45c0686811c68989d6576748475a60bf53fc2
+Message: Automatic deploy lock
+```
+
+You can also manually acquire and release the lock
+
+```
+mrsk lock acquire -m "Doing maintanence"
+```
+
+```
+mrsk lock release
+```
+
 ## Stage of development
 
 This is beta software. Commands may still move around. But we're live in production at [37signals](https://37signals.com).

data/lib/mrsk/cli/accessory.rb

@@ -1,33 +1,38 @@
 class Mrsk::Cli::Accessory < Mrsk::Cli::Base
   desc "boot [NAME]", "Boot new accessory service on host (use NAME=all to boot all accessories)"
   def boot(name)
-    if name == "all"
-      MRSK.accessory_names.each { |accessory_name| boot(accessory_name) }
-    else
-      with_accessory(name) do |accessory|
-        directories(name)
-        upload(name)
+    with_lock do
+      if name == "all"
+        MRSK.accessory_names.each { |accessory_name| boot(accessory_name) }
+      else
+        with_accessory(name) do |accessory|
+          directories(name)
+          upload(name)
 
-        on(accessory.host) do
-          execute *MRSK.auditor.record("Booted #{name} accessory"), verbosity: :debug
-          execute *accessory.run
-        end
+          on(accessory.hosts) do
+            execute *MRSK.registry.login
+            execute *MRSK.auditor.record("Booted #{name} accessory"), verbosity: :debug
+            execute *accessory.run
+          end
 
-        audit_broadcast "Booted accessory #{name}" unless options[:skip_broadcast]
+          audit_broadcast "Booted accessory #{name}" unless options[:skip_broadcast]
+        end
       end
     end
   end
 
   desc "upload [NAME]", "Upload accessory files to host", hide: true
   def upload(name)
-    with_accessory(name) do |accessory|
-      on(accessory.host) do
-        accessory.files.each do |(local, remote)|
-          accessory.ensure_local_file_present(local)
-
-          execute *accessory.make_directory_for(remote)
-          upload! local, remote
-          execute :chmod, "755", remote
+    with_lock do
+      with_accessory(name) do |accessory|
+        on(accessory.hosts) do
+          accessory.files.each do |(local, remote)|
+            accessory.ensure_local_file_present(local)
+
+            execute *accessory.make_directory_for(remote)
+            upload! local, remote
+            execute :chmod, "755", remote
+          end
         end
       end
     end
@@ -35,10 +40,12 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base
 
   desc "directories [NAME]", "Create accessory directories on host", hide: true
   def directories(name)
-    with_accessory(name) do |accessory|
-      on(accessory.host) do
-        accessory.directories.keys.each do |host_path|
-          execute *accessory.make_directory(host_path)
+    with_lock do
+      with_accessory(name) do |accessory|
+        on(accessory.hosts) do
+          accessory.directories.keys.each do |host_path|
+            execute *accessory.make_directory(host_path)
+          end
         end
       end
     end
@@ -46,38 +53,46 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base
 
   desc "reboot [NAME]", "Reboot existing accessory on host (stop container, remove container, start new container)"
   def reboot(name)
-    with_accessory(name) do |accessory|
-      stop(name)
-      remove_container(name)
-      boot(name)
+    with_lock do
+      with_accessory(name) do |accessory|
+        stop(name)
+        remove_container(name)
+        boot(name)
+      end
     end
   end
 
   desc "start [NAME]", "Start existing accessory container on host"
   def start(name)
-    with_accessory(name) do |accessory|
-      on(accessory.host) do
-        execute *MRSK.auditor.record("Started #{name} accessory"), verbosity: :debug
-        execute *accessory.start
+    with_lock do
+      with_accessory(name) do |accessory|
+        on(accessory.hosts) do
+          execute *MRSK.auditor.record("Started #{name} accessory"), verbosity: :debug
+          execute *accessory.start
+        end
       end
     end
   end
 
   desc "stop [NAME]", "Stop existing accessory container on host"
   def stop(name)
-    with_accessory(name) do |accessory|
-      on(accessory.host) do
-        execute *MRSK.auditor.record("Stopped #{name} accessory"), verbosity: :debug
-        execute *accessory.stop, raise_on_non_zero_exit: false
+    with_lock do
+      with_accessory(name) do |accessory|
+        on(accessory.hosts) do
+          execute *MRSK.auditor.record("Stopped #{name} accessory"), verbosity: :debug
+          execute *accessory.stop, raise_on_non_zero_exit: false
+        end
       end
     end
   end
 
   desc "restart [NAME]", "Restart existing accessory container on host"
   def restart(name)
-    with_accessory(name) do
-      stop(name)
-      start(name)
+    with_lock do
+      with_accessory(name) do
+        stop(name)
+        start(name)
+      end
     end
   end
 
@@ -87,7 +102,7 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base
       MRSK.accessory_names.each { |accessory_name| details(accessory_name) }
     else
       with_accessory(name) do |accessory|
-        on(accessory.host) { puts capture_with_info(*accessory.info) }
+        on(accessory.hosts) { puts capture_with_info(*accessory.info) }
       end
     end
   end
@@ -108,14 +123,14 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base
 
       when options[:reuse]
         say "Launching command from existing container...", :magenta
-        on(accessory.host) do
+        on(accessory.hosts) do
           execute *MRSK.auditor.record("Executed cmd '#{cmd}' on #{name} accessory"), verbosity: :debug
           capture_with_info(*accessory.execute_in_existing_container(cmd))
         end
 
       else
         say "Launching command from new container...", :magenta
-        on(accessory.host) do
+        on(accessory.hosts) do
           execute *MRSK.auditor.record("Executed cmd '#{cmd}' on #{name} accessory"), verbosity: :debug
           capture_with_info(*accessory.execute_in_new_container(cmd))
         end
@@ -134,7 +149,7 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base
 
       if options[:follow]
         run_locally do
-          info "Following logs on #{accessory.host}..."
+          info "Following logs on #{accessory.hosts}..."
           info accessory.follow_logs(grep: grep)
           exec accessory.follow_logs(grep: grep)
         end
@@ -142,25 +157,27 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base
         since = options[:since]
         lines = options[:lines].presence || ((since || grep) ? nil : 100) # Default to 100 lines if since or grep isn't set
 
-        on(accessory.host) do
+        on(accessory.hosts) do
           puts capture_with_info(*accessory.logs(since: since, lines: lines, grep: grep))
         end
       end
     end
   end
 
-  desc "remove [NAME]", "Remove accessory container and image from host (use NAME=all to remove all accessories)"
+  desc "remove [NAME]", "Remove accessory container, image and data directory from host (use NAME=all to remove all accessories)"
   option :confirmed, aliases: "-y", type: :boolean, default: false, desc: "Proceed without confirmation question"
   def remove(name)
-    if name == "all"
-      MRSK.accessory_names.each { |accessory_name| remove(accessory_name) }
-    else
-      if options[:confirmed] || ask("This will remove all containers and images for #{name}. Are you sure?", limited_to: %w( y N ), default: "N") == "y"
-        with_accessory(name) do
-          stop(name)
-          remove_container(name)
-          remove_image(name)
-          remove_service_directory(name)
+    with_lock do
+      if name == "all"
+        MRSK.accessory_names.each { |accessory_name| remove(accessory_name) }
+      else
+        if options[:confirmed] || ask("This will remove all containers, images and data directories for #{name}. Are you sure?", limited_to: %w( y N ), default: "N") == "y"
+          with_accessory(name) do
+            stop(name)
+            remove_container(name)
+            remove_image(name)
+            remove_service_directory(name)
+          end
         end
       end
     end
@@ -168,29 +185,35 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base
 
   desc "remove_container [NAME]", "Remove accessory container from host", hide: true
   def remove_container(name)
-    with_accessory(name) do |accessory|
-      on(accessory.host) do
-        execute *MRSK.auditor.record("Remove #{name} accessory container"), verbosity: :debug
-        execute *accessory.remove_container
+    with_lock do
+      with_accessory(name) do |accessory|
+        on(accessory.hosts) do
+          execute *MRSK.auditor.record("Remove #{name} accessory container"), verbosity: :debug
+          execute *accessory.remove_container
+        end
       end
     end
   end
 
   desc "remove_image [NAME]", "Remove accessory image from host", hide: true
   def remove_image(name)
-    with_accessory(name) do |accessory|
-      on(accessory.host) do
-        execute *MRSK.auditor.record("Removed #{name} accessory image"), verbosity: :debug
-        execute *accessory.remove_image
+    with_lock do
+      with_accessory(name) do |accessory|
+        on(accessory.hosts) do
+          execute *MRSK.auditor.record("Removed #{name} accessory image"), verbosity: :debug
+          execute *accessory.remove_image
+        end
       end
     end
   end
 
   desc "remove_service_directory [NAME]", "Remove accessory directory used for uploaded files and data directories from host", hide: true
   def remove_service_directory(name)
-    with_accessory(name) do |accessory|
-      on(accessory.host) do
-        execute *accessory.remove_service_directory
+    with_lock do
+      with_accessory(name) do |accessory|
+        on(accessory.hosts) do
+          execute *accessory.remove_service_directory
+        end
       end
     end
   end