shippy 0.2.8 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fe36006872a9b130eecbfa26b391a3a645dafaced62917c530ac9510944abd8
-  data.tar.gz: a8c0268d4cdb6c776600a21038eeb5de722c7601a770a8f33630bb8b414f0fc6
+  metadata.gz: c8a547859425588ab2d87d11010d8650d8b1d5ee67b6abe1239aa1215c8799ed
+  data.tar.gz: bab2f41d53d11eda45e4e7e70d09bda20e09d2ca6d239a1d0985c3d796a62766
 SHA512:
-  metadata.gz: 7b70994648b3f4c7c842460b335faf0f9a70ae62fff47a3236bcf145d052d45a189c05bddf72cbc1be14ce692f854366df846b925fa248a7ca841c65354a7340
-  data.tar.gz: abd35fa707247d73707c3c41ec15e5f65cb46d01a386aa48a7c003f92640b341ccb3cfd229224e03c759dcdf064cf2cfd960663bc0af79c085ea866897a51dd5
+  metadata.gz: c44eaa3a47d6e8c13c43d41a4fc676e9c9347459c15ef7c4e44ed134c9b99e15d8dfcb6934a82313b1840c7ee69ad450555890de26cd8b4ac94f436ea0daff79
+  data.tar.gz: 534231ef52cb40213a44c969f53c4f479f6573a5a299c3a03ac5327ba2be4a2e8dec1591ccc56c4ae5f5c85d96c87c41b3274c09d5139242adf727999eb373c1

data/README.md

@@ -2,14 +2,17 @@
 
 Shippy is a lightweight container orchestration tool designed specifically for homelabs. It combines the simplicity of Docker Compose with a powerful Ruby DSL, inspired by the deployment workflows of Capistrano and Kamal.
 
-## Features
+## ✨ Features
 
-- Ruby DSL to generate the docker-compose YAML files
-- Centralized source to define secrets
-- Uses Traefik as a reverse proxy with SSL wildcard support
-- Manage the entire lab with a local `bin/shippy` command.
+- Ruby DSL to generate cleaner, DRYer docker-compose.yml files.
+- Server bootstrapping to automatically provision a raw server with Docker and necessary dependencies.
+- Built-in rollbacks to afely revert to previous deployments with a single command.
+- Immutable deployments which automatically pins image digests (sha256) during deployment to prevent upstream changes from breaking your apps.
+- Centralized secrets for securely defining and injecting encrypted credentials.
+- First-class Traefik support comes as a built-in reverse proxy routing with SSL wildcard certificate generation.
+- Garbage collection which defines prune commands to keep your homelab server's storage clean.
 
-## 🚀 Getting Started
+## 🚀 Getting started
 
 Install the gem:
 
@@ -17,7 +20,7 @@ Install the gem:
 $ gem install shippy
 ```
 
-In you homelab directory execute:
+Make your homelab directory:
 
 ```shell
 home$ mkdir homelab && cd homelab
@@ -29,6 +32,48 @@ This creates the core structure:
 - `config/`: Shippy configuration and secrets.
 - `bin/shippy`: Your local entry point for all commands.
 
+### 🛠️ Provision & deploy
+
+Shippy can automatically prepare a brand new Ubuntu/Debian server for you. Once your `config/shippy.yml` is configured with your host IP and SSH details, run:
+
+```shell
+homelab$ bin/shippy setup
+```
+
+This command will:
+
+- Log into your server and install `curl`, `docker.io`, and `docker-compose` via `apt-get` (if missing).  
+- Create the required directory structures (`apps/` and `backups/`).  
+- Deploy all of your configured apps.  
+
+### 🕹️ CLI commands & app management
+
+Shippy features both global commands (for the whole lab) and granular commands (for specific apps).
+
+Global commands:
+
+- `bin/shippy deploy` - Deploys or updates all applications in your `apps/` directory.  
+- `bin/shippy stop` - Stops all applications.  
+- `bin/shippy refresh` - Pulls the latest images and restarts all services.  
+- `bin/shippy prune all` - Cleans up unused images (older than 7 days) and stopped containers (older than 3 days).  
+
+Granular app commands (`bin/shippy app <command> <name>`):
+
+- `bin/shippy app deploy proxy` - Deploys only the `proxy` app.  
+- `bin/shippy app logs proxy --follow` - Tails the logs for the proxy app.  
+- `bin/shippy app restart proxy --service traefik` - Restarts only the specific traefik service inside the proxy app.  
+- `bin/shippy app status proxy` - Shows the current ps status of the app's containers.  
+- `bin/shippy app compile proxy` - Generates the files that would be copied to the server in the `builds/apps/proxy/` directory, useful for debugging the files without actually deploying them.
+
+### ⏪ Instant rollbacks
+
+Because Shippy backs up your previous deployment directories (configurable via `keep_releases`), you can easily roll back if an update breaks your app:
+
+```shell
+# Rollback the proxy app by 1 version
+bin/shippy app rollback proxy -n 1
+```
+
 ### Docker compose DSL:
 
 Conventions:
@@ -76,6 +121,173 @@ By running `bin/shippy deploy proxy` the DSL gets converted to YAML and deployed
 
 See the examples directory for more options.
 
+### ⚙️ Configuration
+
+Shippy uses a central configuration file (located at `config/shippy.yml`) to define your lab environment.
+
+#### Global Settings
+
+Here is an example configuration:
+
+```yaml
+host: 'homelab.local'
+ssh:
+  user: name
+wildcard_domain: 'lab.example.com'
+deploy_to: '/var/lib/homelab'
+secrets_file: 'config/secrets.yml.enc'
+keep_releases: 5
+media_path: '/media/storage'
+```
+
+Shippy is designed to automatically secure your services with a wildcard SSL certificate (`*.lab.example.com`). To achieve this, it relies on a `DNS-01` challenge.
+
+* You must use Cloudflare as your DNS provider so Traefik can automatically verify domain ownership via their API.  
+* You need to configure a wildcard DNS record (`*.lab.example.com`) in Cloudflare pointing to the IP address of your homelab server.  
+
+#### Secrets management
+
+Your secrets are stored in an encrypted file defined by secrets_file (e.g., `config/secrets.yml.enc`).
+
+Secrets in this file are scoped to the specific app they belong to. For example, if you have an app named `proxy`, your secrets file structure should look like this:
+
+```yaml
+proxy:
+  cloudflare_email: "user@example.com"
+  cloudflare_token: "your-api-token"
+```
+
+Inside your `apps/proxy/docker-compose.rb`, calling `secrets(:cloudflare_email)` will fetch the value specifically nested under the proxy key. This ensures services only have access to their own credentials.
+
+Run `bin/shippy secrets edit` to safely modify them using your default `$EDITOR`.
+
+⚠️ Secrets are only encrypted at rest within the `config/secrets.yml.enc` file. During compilation and deployment, these secrets are injected as plaintext into the generated `docker-compose.yml` files and will be visible in your local `builds/` directory. The primary intent of this feature is to allow you to safely commit your homelab configuration to Git without exposing keys in your repository, not to provide strict, enterprise-grade runtime security. There is an open issue to integrate natively with Docker Compose secrets [here](https://gitlab.com/mrbobin/shippy/-/issues/1).
+
+#### 🚦 Exposing Apps (Traefik)
+
+To make an app accessible from the outside world, use the `use_traefik` helper inside your service block.
+
+```ruby
+use_traefik(name: 'home-assistant', port: 8123)
+```
+
+This automatically generates the labels required to expose the container at `home-assistant.lab.example.com`.
+
+- The name dictates the subdomain.  
+- The port is optional if your container only exposes a single port, but it __should be explicitly defined__ if the container exposes multiple internal ports.
+
+Sometimes you need more complex routing than just matching the host. You can pass a block to use_traefik to append custom Traefik routing rules.
+
+```ruby
+use_traefik(name: 'matrix', port: 80) do |rule|
+  "#{rule} && PathPrefix(`/.well-known/`)"
+end
+```
+
+If a single container provides multiple web interfaces (like MinIO, which has an API and a web console), you can manually build and append the Traefik labels using `build_traefik_labels`:
+
+```ruby
+labels do
+  all_labels = ["traefik.enable=true"]
+  all_labels += build_traefik_labels(name: :minio, port: 9000)
+  all_labels += build_traefik_labels(name: :mconsole, port: 9001)
+
+  all_labels
+end
+```
+
+#### 🎛 Overriding defaults
+
+To keep your files clean, Shippy provides a `use_default_option`s method. Calling this automatically applies default Docker networks for Traefik access, a standard restart policy (like `unless-stopped`), and default logging limits so your drives don't fill up.
+
+If you need fine-grained control, you can omit `use_default_options` and specify exactly what you want:
+
+```ruby
+networks { [ 'backend', 'lan_access' ] } # 'lan_access' is required by Traefik(if used on the service)
+use_default_restart
+use_default_logging
+```
+
+This is highly useful when placing an app on an isolated network without exposing it to the default network.
+
+#### Post-deployment hooks
+
+Sometimes a container needs to run commands immediately after it boots up (like database migrations or setting up initial admin users). You can define an array of commands in a `hooks` block, and Shippy will execute them sequentially inside the running container:
+
+```ruby
+hooks do
+  [
+    'bundle exec rails db:create',
+    'bundle exec rails db:migrate'
+  ]
+end
+```
+
+#### DRY service configurations
+
+Shippy allows you to define custom helper methods directly inside the `Shippy.define` block to share logic across multiple services.
+
+- Use `x.<key>` to access variables from your global config file (like `x.media_path`).  
+- Use `app.<method_name>` to call your custom methods from inside a service block.  
+
+```ruby
+Shippy.define do
+  # 1. Define a shared helper method
+  def nextcloud_volumes
+    [
+      # 'x' accesses properties from your global config file
+      "#{x.media_path}/nextcloud/html:/var/www/html",
+      "#{x.media_path}/nextcloud/apps:/var/www/html/custom_apps",
+      "#{x.media_path}/nextcloud/config:/var/www/html/config",
+      "#{x.media_path}/nextcloud/data:/var/www/html/data",
+      "#{x.media_path}/nextcloud/themes:/var/www/html/themes"
+    ]
+  end
+
+  service :nextcloud do
+    image { 'nextcloud:fpm-alpine' }
+    
+    # 2. Call the helper method using 'app'
+    volumes { app.nextcloud_volumes }
+  end
+
+  service :nextcloud_proxy do
+    image { 'nginx:alpine' }
+    depends_on { ['nextcloud'] }
+    
+    # 3. Combine unique volumes with the shared volumes array
+    volumes { ["./nginx/nginx.conf:/etc/nginx/nginx.conf"] + app.nextcloud_volumes }
+    use_traefik(name: 'box')
+  end
+end
+```
+
+#### App files & ERB templating
+
+Any files or directories you place inside an app's directoy (alongside `docker-compose.rb`) are automatically copied over to your homelab server during deployment. This makes it incredibly easy to bundle configuration files (like Nginx confs, Prometheus rules, or Traefik configs) right next to the service that uses them.
+
+However, there are two crucial rules to understand about how Shippy handles these files:
+
+1. Avoid bind mounting to the app directory  
+  Because Shippy keeps track of your deployment history (using the `keep_releases` setting in your config), the actual directory where your app runs gets rotated and moved to a backups path on every deploy. Do not use relative bind mounts for data that changes or needs to persist (e.g., `./data:/var/lib/mysql`). When you deploy again, the folder moves, and your container will start with a fresh, empty directory! Always bind mount your persistent data to a stable, absolute path on your server, such as the `media_path` defined in your `shippy.yml`, or use standard Docker named volumes.
+
+2. ERB templating for dynamic configs  
+  Shippy allows you to use Ruby's ERB templating inside your supplemental files. If you need to inject secrets, loop through configurations, or access global variables, simply append `.erb` to the file name.  
+  During deployment, Shippy will evaluate the Ruby code, strip the `.erb` extension, and upload the fully rendered file to your server.
+
+  Example: `apps/proxy/traefik/config.yml.erb` In this Traefik config, we can securely inject the Cloudflare email right from our encrypted `secrets.yml.enc` file:
+
+```yaml
+certificatesResolvers:
+  ssl-resolver:
+    acme:
+      # Shippy dynamically injects this secret during deploy!
+      email: <%= secrets(:cloudflare_email) %>
+      storage: /etc/traefik/acme/acme.json
+      dnsChallenge:
+        provider: cloudflare
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/shippy/cli/templates/config/shippy.yml

@@ -2,7 +2,6 @@ host: 'homelab.local'
 ssh:
   user: root
 wildcard_domain: 'local.homelab.com'
-local_domain: local
 deploy_to: '/var/lib/homelab'
 secrets_file: 'config/secrets.yml.enc'
 keep_releases: 10

data/lib/shippy/compose.rb

@@ -52,7 +52,7 @@ module Shippy
     end
 
     delegate :x, to: Shippy
-    delegate :wildcard_domain, :local_domain, to: :x
+    delegate :wildcard_domain, to: :x
 
     private
 

data/lib/shippy/service.rb

@@ -96,7 +96,7 @@ module Shippy
     end
 
     delegate :x, to: Shippy
-    delegate :wildcard_domain, :local_domain, to: :x
+    delegate :wildcard_domain, to: :x
 
     def hooks
       if block_given?

data/lib/shippy/version.rb

@@ -1,3 +1,3 @@
 module Shippy
-  VERSION = "0.2.8"
+  VERSION = "0.2.9"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shippy
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.2.9
 platform: ruby
 authors:
 - Marius Bobin