kamal-skiff 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdb99cc1736f7ff3c6057f0617d784fb027850139f6e838469e1f1bde812c03a
-  data.tar.gz: e3600a4d93fc6e3eb60761c6a7684394ed10319ce4a947027cf7681f99544b02
+  metadata.gz: b8e59e20b087bcae677641f4f8e1061dc9c7d2b2c4cceb00cd41fd597b8e7252
+  data.tar.gz: c6e3c1840db9d1ac8344be6ae13659fbb0ff05c1763a98836b302347a182cc50
 SHA512:
-  metadata.gz: bcda624fab93d5a02dc361c1587108a2bbd4db39c1d605e87da71253a82e7fdddacda37461a989fc523d3c1cea440ca741e08516ff74fbefee4af26eaf1e6587
-  data.tar.gz: 8dd01d371bdc2851d8777301c87cbefc305745b75b8c6f572ad6a1c83c072d2b272ab8f598a9a21ccbdb3095ea0d11c8046a8cdac97a6ff2ab6d1cbc776117fc
+  metadata.gz: 6e85dd1dbea08e3a8cb821a6583e9f67b62a59faba8dc49020c2cfaa045265546a654b82481fac2e0426a7db9658181c4a1e7a3caca0fd2e5eb4fa7fa3337ffb
+  data.tar.gz: 7d56f92e3fd93c1f45e92b9e7c86e53cb873ee51f8b88caf971fa31ea89e23439905ac6e72f79cbfa30f73e5d913dc3003ee03ec3a674bbda2e2dd51783b0c0b

data/README.md

@@ -2,44 +2,74 @@
 
 Skiff uses [Kamal](https://kamal-deploy.org) to deploy static sites using nginx with Server-Side Includes (SSI).
 
-## Local development
+Understand the why and the how in this introduction video: https://www.youtube.com/watch?v=YoabUEzpM6k
+
+## Setting up your first Skiff site
+
+1. Create a new site scaffold and enter the project:
+   ```sh
+   skiff new mysite
+   cd mysite
+   ```
 
-If you have a Ruby environment available, you can install Skiff globally with:
+2. Add your site files under `public/` (for example, `public/index.html` and includes in `public/_includes/`).
 
-```sh
-gem install kamal-skiff
-```
+3. Put the site in a Git repository and push it to GitHub, since the server auto-pulls from git:
+   ```sh
+   git init
+   git add .
+   git commit -m "Initial site"
+   git branch -M master
+   git remote add origin git@github.com:username/repo.git
+   git push -u origin master
+   ```
 
-Then run `skiff dev` to start the development server.
+4. Set `GIT_URL` in `.kamal/secrets` so the server can pull your repository (relying on ENV GITHUB_TOKEN):
+   ```bash
+   GIT_URL=https://x-access-token:${GITHUB_TOKEN}@github.com/username/repo.git
+   ```
 
-...otherwise, you can run a dockerized version via an alias (add this to your .bashrc or similar to simplify re-use). On macOS, use:
+### If you need to create a GitHub access token
 
-```sh
-alias skiff-dev="docker build -t skiff-site . && docker run -it --rm -p 4000:80 -v ./public:/site/public --name skiff-site skiff-site nginx '-g daemon off;'"
-alias skiff="docker run -it --rm -v '${PWD}:/workdir' -v /run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock -e SSH_AUTH_SOCK='/run/host-services/ssh-auth.sock' -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/basecamp/kamal-skiff:latest"
-```
+- Go to **GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens**.
+  - Direct link: https://github.com/settings/tokens?type=beta
+- Click **Generate new token** and configure:
+  - **Token name**: A descriptive name (e.g., `mysite-deploy`)
+  - **Expiration**: Choose an appropriate duration
+  - **Repository access**: Select "Only select repositories" → choose your site's repository
+  - **Permissions**: Repository permissions → **Contents**: `Read-only`
+- Click **Generate token** and copy the value.
+- Store the token in 1Password:
+  - Use the **Deploy** vault
+  - Create or update an item for your site (e.g., `mysite.do`)
+  - Add the token as a field named `GITHUB_TOKEN`
 
-Then run `skiff-dev` to start the development server, and use `skiff [command]` for everything else.
+5. Update `config/deploy.yml` with your server address in `servers` and confirm the `image` name.
 
-## Deploying the site for the first time
+Kamal 2 uses a local registry by default (`registry.server: localhost:5555`), so you do not need to configure remote registry credentials unless you change that setting.
 
-First ensure that you've set `GIT_URL` to a repository address with a valid access token embedded in the `.env` file. This access token must have access to pull from the git repository in question (see [personal access tokens for GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for an example).
+6. Deploy your site:
+   ```sh
+   skiff deploy
+   ```
 
-Then you must also setup an access token for your Docker image repository (see [Create and manage access tokens for Docker Hub](https://docs.docker.com/security/for-developers/access-tokens/) for an example).
+   This will install Docker on your server (using `apt-get`) if it is not already available.
 
-Finally, you must add the server address into `config/deploy.yml`, and ensure that the image and repository configurations are correct.
+If you're upgrading an existing site from Kamal 1, run `kamal upgrade` once (and `kamal upgrade -d staging` for staging) before your next `skiff deploy`.
+
+## Local development
 
-Now you're ready to run `skiff deploy` to deploy your site to the server. This will install Docker on your server (using `apt-get`), if it isn't already available.
+Run `skiff dev` to start the development server on localhost:4000.
 
 ## Deploying changes to production
 
-Changes checked into git are automatically pulled onto the Skiff server every 10 seconds. So all you have to do is checkin your changes and push them.
+Changes checked into git are automatically pulled onto the Skiff server every 10 seconds. So all you have to do is check in your changes and push them.
 
-If you need to change the nginx configuration in `config/server.conf`, make your changes to that file, check them into git and push, and then run `skiff restart` to test the configuration file and restart the server if it's valid.
+If you need to change the nginx configuration in `config/server.conf`, make your changes to that file, check them into git, and push. Skiff will detect the update, validate the new config, and reload nginx automatically.
 
 ## Deploying changes to staging first
 
-To use a staging server, you must set `GIT_BRANCH` in .env to the branch you're using for staging. Then you can deploy the site to a staging server using `skiff deploy --staging`, which will use the configuration in `config/deploy.staging.yml`, and start pulling updates from the branch specified.
+To use a staging server, set `GIT_BRANCH` in `config/deploy.staging.yml` under `env.clear` to the branch you're using for staging. Then you can deploy the site to a staging server using `skiff deploy --staging`, which will use the configuration in `config/deploy.staging.yml`, and start pulling updates from the branch specified.
 
 ## Flushing etag caches after changing include files
 

data/lib/skiff/cli.rb

@@ -50,7 +50,7 @@ class Skiff::Cli < Thor
   desc "refresh", "Force pull latest changes from git"
   option :staging, aliases: "-s", type: :boolean, default: false, desc: "On staging server"
   def refresh
-    kamal_exec 'git checkout -f & git pull \$GIT_URL'
+    kamal_exec 'cd /tmp/repo && git fetch --depth 1 origin ${GIT_BRANCH:-HEAD} && git reset --hard FETCH_HEAD && rsync -a --delete --exclude=config/ --exclude=serve /tmp/repo/ /site/'
   end
 
   desc "logs", "Follow logs from server"

data/lib/skiff/templates/Dockerfile

@@ -1,8 +1,8 @@
 FROM nginx:latest
 
-# Install git to provide polling updates
+# Install git and rsync to provide polling updates
 RUN apt-get update -qq && \
-    apt-get install --no-install-recommends -y git && \
+    apt-get install --no-install-recommends -y git rsync && \
     rm -rf /var/lib/apt/lists /var/cache/apt/archives
 
 # Site lives here

data/lib/skiff/templates/README.md.tt

@@ -13,24 +13,26 @@ gem install kamal-skiff
 ...otherwise, you can run a dockerized version via an alias (add this to your .bashrc or similar to simplify re-use). On macOS, use:
 
 ```sh
-alias skiff="docker run -it --rm -v '${PWD}:/workdir' -v '/run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock' -e SSH_AUTH_SOCK='/run/host-services/ssh-auth.sock' -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/basecamp/kamal-skiff:latest"
+alias skiff='docker run -it --rm -v "${PWD}:/workdir" -v /run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock -e SSH_AUTH_SOCK="/run/host-services/ssh-auth.sock" -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/basecamp/kamal-skiff:latest'
 ```
 
 Then run `skiff dev` to start the development server.
 
 ## Deploying changes to production (or staging)
 
-Changes checked into git are automatically pulled onto the Skiff server every 10 seconds. So all you have to do is checkin your changes and push them.
+Changes checked into git are automatically pulled onto the Skiff server every 10 seconds. So all you have to do is check in your changes and push them.
 
-If you need to change the nginx configuration in `config/server.conf`, make your changes to that file, check them into git and push, and then run `skiff restart` to test the configuration file and restart the server if it's valid.
+If you need to change the nginx configuration in `config/server.conf`, make your changes to that file, check them into git, and push. Skiff will detect the update, validate the new config, and reload nginx automatically.
 
 ## Deploying the site for the first time
 
-First ensure that you've set `GIT_URL` to a repository address with a valid access token embedded in the `.env` file. This access token must have access to pull from the git repository in question (see [personal access tokens for GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for an example).
+If this site was originally deployed with Kamal 1, run `kamal upgrade` once (and `kamal upgrade -d staging` for staging) before your next `skiff deploy`.
 
-Then you must also setup an access token for your Docker image repository (see [Create and manage access tokens for Docker Hub](https://docs.docker.com/security/for-developers/access-tokens/) for an example).
+First ensure that you've set `GIT_URL` to a repository address with a valid access token embedded in `.kamal/secrets`. This access token must have access to pull from the git repository in question (see [personal access tokens for GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for an example).
 
-Finally, you must add the server address into `config/deploy.yml`, and ensure that the image and repository configurations are correct.
+Kamal 2 uses a local registry by default (`registry.server: localhost:5555`), so you do not need to configure remote registry credentials unless you change that setting.
+
+Finally, you must add the server address into `config/deploy.yml`, and ensure that the image configuration is correct.
 
 Now you're ready to run `skiff deploy` to deploy your site to the server. This will install Docker on your server (using `apt-get`), if it isn't already available.
 

data/lib/skiff/templates/config/deploy.staging.yml

@@ -1,4 +1,4 @@
-# Deploy your site to a staging server with skiff stage
+# Deploy your site to a staging server with skiff deploy --staging
 servers:
   - 192.168.0.2
 

data/lib/skiff/templates/config/deploy.yml.tt

@@ -8,25 +8,18 @@ image: <%= @user_name %>/<%= @site_name %>
 servers:
   - 192.168.0.1
 
-# Use GIT_URL from env to auto-update site via git pulls.
-# Remember to run `kamal env push` after making changes!
+# Use GIT_URL from secrets to auto-update site via git pulls.
 env:
   secret:
     - GIT_URL
 
-# Credentials for your image host.
+# Use Kamal's local registry.
 registry:
-  # Specify the registry server, if you're not using Docker Hub
-  # server: registry.digitalocean.com / ghcr.io / ...
-  username: <%= @user_name %>
+  server: localhost:5555
 
-  # Always use an access token rather than real password when possible.
-  password:
-    - SKIFF_REGISTRY_PASSWORD
-
-# Check /up against 80
-healthcheck:
-  port: 80
+proxy:
+  healthcheck:
+    path: /up
 
 # Use a different ssh user than root
 # ssh:

data/lib/skiff/templates/config/server.conf

@@ -19,7 +19,7 @@ server {
   error_page 404 /_errors/404.html;
 
   # Folders starting with _ are not publicly accessible
-  location ~ ^/_$ {
+  location ~ ^/_ {
     internal;
   }
 

data/lib/skiff/templates/dotfiles/dockerignore

@@ -1,2 +1,6 @@
-# Ignore env file
+# Ignore local secrets
+/.kamal/secrets*
 /.env
+
+# Ignore git directory (clone fresh at runtime to avoid layer caching issues)
+/.git

data/lib/skiff/templates/dotfiles/gitignore

@@ -1,2 +1,2 @@
-# Ignore env file
+/.kamal/secrets*
 /.env

data/lib/skiff/templates/dotfiles/kamal-secrets.tt

@@ -0,0 +1 @@
+GIT_URL=https://x-access-token:YOUR_TOKEN@github.com/<%= @user_name %>/<%= @site_name %>.git

data/lib/skiff/templates/serve

@@ -1,17 +1,117 @@
 #!/bin/bash
-set -e
+set -eo pipefail
+
+REPO_DIR=/tmp/repo
+SITE_DIR=/site
+
+log() {
+  if [ $# -gt 0 ]; then
+    echo "⛵ [skiff] $*"
+  else
+    sed 's/^/⛵ [skiff] /'
+  fi
+}
+
+sync_continuously() {
+  sleep 5  # Wait for nginx
 
-polling_pull() {
   while true; do
-    echo "Pulling latest..."
-    git checkout -f || true
-    git pull $GIT_URL $GIT_BRANCH || true
+    if sync; then
+      log "Synced."
+    else
+      log "Error during sync, will retry..."
+    fi
+
     sleep 10
   done
 }
 
-# When GIT_URL is set start polling in the background
-[[ "$GIT_URL" ]] && polling_pull &
+sync() {
+  sync_site_assets && sync_server_conf
+}
+
+sync_site_assets() {
+  log "Fetching ${GIT_BRANCH:-HEAD}..."
+
+  if [ -d "$REPO_DIR/.git" ]; then
+    # Subsequent runs: fetch and check for changes
+    cd "$REPO_DIR"
+    OLD_HEAD=$(git rev-parse HEAD)
+    git fetch --depth 1 origin "${GIT_BRANCH:-HEAD}" 2>&1 | log
+
+    # Skip sync if no changes
+    if [ "$OLD_HEAD" = "$(git rev-parse FETCH_HEAD)" ]; then
+      log "Already up to date."
+      return 0
+    fi
+    git reset --hard FETCH_HEAD 2>&1 | log
+  else
+    # First run: shallow clone
+    rm -rf "$REPO_DIR"
+    git clone --depth 1 ${GIT_BRANCH:+--branch "$GIT_BRANCH"} "$GIT_URL" "$REPO_DIR" 2>&1 | log
+  fi
+
+  # Sync to site
+  rsync -a --delete --exclude='config/' --exclude='serve' "$REPO_DIR/" "$SITE_DIR/"
+}
+
+sync_server_conf() {
+  local repo_dir="$REPO_DIR/config"
+  local site_dir="$SITE_DIR/config"
+  local backup_dir="$SITE_DIR/config/.bak"
+  local changed=false
+
+  mkdir -p "$site_dir"
+
+  for repo_conf in "$repo_dir"/*.conf; do
+    [ -f "$repo_conf" ] || continue
+    local name=$(basename "$repo_conf")
+    local site_conf="$site_dir/$name"
+
+    if [ -f "$site_conf" ] && cmp -s "$repo_conf" "$site_conf"; then
+      continue
+    fi
+
+    changed=true
+    break
+  done
+
+  [ "$changed" = true ] || return 0
+
+  log "Detected change to config/*.conf, validating and reloading nginx..."
+
+  # Back up current config files
+  rm -rf "$backup_dir"
+  mkdir -p "$backup_dir"
+  for f in "$site_dir"/*.conf; do
+    [ -f "$f" ] && cp "$f" "$backup_dir/"
+  done
+
+  # Copy new config files
+  for repo_conf in "$repo_dir"/*.conf; do
+    [ -f "$repo_conf" ] && cp "$repo_conf" "$site_dir/"
+  done
+
+  if nginx -t 2>&1 | log && nginx -s reload 2>&1 | log; then
+    rm -rf "$backup_dir"
+    log "Reloaded nginx with updated config."
+    return 0
+  else
+    # Restore backup
+    if [ -d "$backup_dir" ]; then
+      for f in "$backup_dir"/*.conf; do
+        [ -f "$f" ] && cp "$f" "$site_dir/"
+      done
+      rm -rf "$backup_dir"
+      log "Reverted config to last known good version."
+    fi
+
+    log "Config changed, but nginx could not be restarted."
+    return 1
+  fi
+}
+
 
-# Start NGINX in the foreground
+# Start continuously syncing in background if GIT_URL is set
+[[ "$GIT_URL" ]] && sync_continuously &
 nginx -g 'daemon off;'

data/lib/skiff/templates/site.rb

@@ -1,4 +1,5 @@
-template  "dotfiles/env.tt", ".env"
+empty_directory ".kamal"
+template  "dotfiles/kamal-secrets.tt", ".kamal/secrets"
 copy_file "dotfiles/gitignore", ".gitignore"
 copy_file "dotfiles/dockerignore", ".dockerignore"
 

data/lib/skiff/version.rb

@@ -1,3 +1,3 @@
 module Skiff
-  VERSION = "0.2.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,29 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: kamal-skiff
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.5.0
 platform: ruby
 authors:
 - David Heinemeier Hansson
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-26 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: kamal
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -80,7 +79,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
 email: dhh@hey.com
 executables:
 - skiff
@@ -98,8 +96,8 @@ files:
 - lib/skiff/templates/config/deploy.yml.tt
 - lib/skiff/templates/config/server.conf
 - lib/skiff/templates/dotfiles/dockerignore
-- lib/skiff/templates/dotfiles/env.tt
 - lib/skiff/templates/dotfiles/gitignore
+- lib/skiff/templates/dotfiles/kamal-secrets.tt
 - lib/skiff/templates/public/_errors/404.html
 - lib/skiff/templates/public/_includes/footer.html
 - lib/skiff/templates/public/_includes/header.html
@@ -112,7 +110,6 @@ homepage: https://github.com/basecamp/kamal-skiff
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -127,8 +124,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.20
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Deploy static sites using nginx + SSI with Kamal.
 test_files: []

data/lib/skiff/templates/dotfiles/env.tt

@@ -1,2 +0,0 @@
-SKIFF_REGISTRY_PASSWORD=YOUR_TOKEN
-GIT_URL=https://YOUR_TOKEN:@github.com/<%= @user_name %>/<%= @site_name %>.git