kamal-skiff 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5962234770cd990a7c673bf5a77b007bdda292e3a1fa0280c512da53de47cc70
+  data.tar.gz: 1bdbc85dcba5c4ac35f1f06b670d94ed0623298b3e266aff5e8d7c8a9379dec2
+SHA512:
+  metadata.gz: 6105a3cd3883ee27ec8d32fea07d7ebb5833066bb4302260d8dc15dcc794cbfe6aaafcfb1a2665c612fa5adecad7bf1a9eb1b87113ddbbab9cacb8d4d3b18e61
+  data.tar.gz: 1d4ce26e94e4d1462f7522dca52f12b6d7da305e7696d34c84b6221af90ee85f7ede4460acb1308f5637353cf72a784af9d6f43778b7ccee606871168b14777f

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2023 37signals
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,47 @@
+# Skiff
+
+Skiff uses [Kamal](https://kamal-deploy.org) to deploy static sites using nginx with Server-Side Includes (SSI).
+
+## Local development
+
+If you have a Ruby environment available, you can install Skiff globally with:
+
+```sh
+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"
+```
+
+Then run `skiff dev` to start the development server.
+
+## 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).
+
+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).
+
+Finally, you must add the server address into `config/deploy.yml`, and ensure that the image and repository configurations are 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.
+
+## 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.
+
+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.
+
+## 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.
+
+## Flushing etag caches after changing include files
+
+Skiff uses [Server Side Includes](https://nginx.org/en/docs/http/ngx_http_ssi_module.html), which can change independently of your individual HTML files. When that happens, the caching etags for those latter files will not be updated automatically to reflect the change. You can run `skiff flush` to touch all the public HTML files, which will flush the etag cache.
+
+## License
+
+Skiff is released under the [MIT License](https://opensource.org/licenses/MIT).

data/bin/skiff

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+# Prevent failures from being reported twice.
+Thread.report_on_exception = false
+
+require "kamal-skiff"
+
+begin
+  Skiff::Cli.start(ARGV)
+rescue => e
+  puts "  \e[31mERROR (#{e.class}): #{e.message}\e[0m"
+  puts e.backtrace if ENV["VERBOSE"]
+  exit 1
+end

data/lib/kamal-skiff.rb

@@ -0,0 +1,5 @@
+module Skiff
+end
+
+require "skiff/cli"
+require "skiff/version"

data/lib/skiff/cli.rb

@@ -0,0 +1,92 @@
+require "thor"
+
+class Skiff::Cli < Thor
+  include Thor::Actions
+
+  def self.exit_on_failure?() true end
+
+  source_root File.expand_path("templates", __dir__)
+
+  desc "new", "Create a new skiff site [SITE_NAME]"
+  def new(site_name)
+    self.destination_root = File.expand_path(site_name)
+
+    @site_name = site_name
+    @user_name = `whoami`.strip
+
+    eval File.read(File.join(File.dirname(__FILE__), "templates/site.rb"))
+  end
+
+  desc "dev", "Start development server"
+  def dev
+    if File.exist?("Dockerfile")
+      puts "Starting #{site_name} on http://localhost:8080..."
+
+      docker "build -t #{site_name} ."
+      docker "run -it --rm -p 8080:80 -v ./public:/site/public --name #{site_name} #{site_name} nginx '-g daemon off;'"
+    else
+      say "No Dockerfile found in current directory", :red
+    end
+  end
+
+  desc "deploy", "Deploy the site"
+  option :staging, aliases: "-s", type: :boolean, default: false, desc: "On staging server"
+  def deploy
+    kamal "setup"
+  end
+
+  desc "flush", "Flush etags after includes have changed (by touching all html files)"
+  option :staging, aliases: "-s", type: :boolean, default: false, desc: "On staging server"
+  def flush
+    kamal_exec 'find /site/public -type f -name "*.html" -exec touch {} \;'
+  end
+
+  desc "restart", "Restart the nginx server with latest config/server.conf"
+  option :staging, aliases: "-s", type: :boolean, default: false, desc: "On staging server"
+  def restart
+    kamal_exec "nginx -t && nginx -s reload"
+  end
+
+  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'
+  end
+
+  desc "logs", "Follow logs from server"
+  option :staging, aliases: "-s", type: :boolean, default: false, desc: "On staging server"
+  def logs
+    kamal "app logs -f"
+  end
+
+  desc "version", "Show Skiff version"
+  def version
+    say Skiff::VERSION
+  end
+
+  private
+    def empty_directory_with_keep_file(destination, config = {})
+      empty_directory(destination, config)
+      keep_file(destination)
+    end
+
+    def keep_file(destination)
+      create_file("#{destination}/.keep")
+    end
+
+    def site_name
+      @site_name ||= File.basename(Dir.pwd)
+    end
+
+    def docker(command)
+      system "docker #{command}"
+    end
+
+    def kamal(command)
+      system "kamal #{command} #{options[:staging] ? "-d staging" : ""}".strip
+    end
+
+    def kamal_exec(commands)
+      kamal %(app exec --reuse '/bin/bash -c "#{commands}"')
+    end
+end

data/lib/skiff/templates/Dockerfile

@@ -0,0 +1,17 @@
+FROM nginx:latest
+
+# Install git to provide polling updates
+RUN apt-get update -qq && \
+    apt-get install --no-install-recommends -y git && \
+    rm -rf /var/lib/apt/lists /var/cache/apt/archives
+
+# Site lives here
+WORKDIR /site
+
+# Copy site
+COPY . .
+
+# Configure nginx
+RUN echo 'include /site/config/server.conf;' > /etc/nginx/conf.d/default.conf
+
+CMD ["/site/serve"]

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

@@ -0,0 +1,39 @@
+# <%= @site_name.capitalize %>
+
+This site is managed by [Skiff](https://kamal-deploy.org/skiff).
+
+## Local development
+
+If you have a Ruby environment available, you can install Skiff globally with:
+
+```sh
+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"
+```
+
+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.
+
+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.
+
+## 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).
+
+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).
+
+Finally, you must add the server address into `config/deploy.yml`, and ensure that the image and repository configurations are 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.
+
+## Flushing etag caches after changing include files
+
+Skiff uses [Server Side Includes](https://nginx.org/en/docs/http/ngx_http_ssi_module.html), which can change independently of your individual HTML files. When that happens, the caching etags for those latter files will not be updated automatically to reflect the change. You can run `skiff flush` to touch all the public HTML files, which will flush the etag cache.

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

@@ -0,0 +1,8 @@
+# Deploy your site to a staging server with skiff stage
+servers:
+  - 192.168.0.2
+
+# Set this to the git branch the staging server should be pulling from when using auto-updating with GIT_URL
+# env:
+#   clear:
+#     GIT_BRANCH: staging

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

@@ -0,0 +1,33 @@
+# Name of your site. Used to uniquely configure containers.
+service: <%= @site_name %>
+
+# Name of the container image.
+image: <%= @user_name %>/<%= @site_name %>
+
+# Deploy to these servers.
+servers:
+  - 192.168.0.1
+
+# Credentials for your image host.
+registry:
+  # Specify the registry server, if you're not using Docker Hub
+  # server: registry.digitalocean.com / ghcr.io / ...
+  username: <%= @user_name %>
+
+  # Always use an access token rather than real password when possible.
+  password:
+    - SKIFF_REGISTRY_PASSWORD
+
+# Check /up against 80
+healthcheck:
+  port: 80
+
+# Use GIT_URL from env if you want to auto-update site via git pulls.
+# Remember to run `kamal env push` after making changes!
+# env:
+#   secret:
+#     - GIT_URL
+
+# Use a different ssh user than root
+# ssh:
+#   user: app

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

@@ -0,0 +1,34 @@
+server { 
+  listen 80;
+
+  # Configure URL rewrites
+  # rewrite ^/old-pricing$ /pricing last;
+
+  # Only needed if there's no CDN in front
+  gzip on;
+
+  # Turn on SSI with etags
+  ssi on;
+  ssi_last_modified on;
+
+  # All web accessible files live here
+  root /site/public;
+
+  # Map error pages
+  error_page 404 /_errors/404.html;
+
+  # Folders starting with _ are not publicly accessible
+  location ~ ^/_.*$ {
+    internal;
+  }
+
+  # Make /up look for /site/public/up.html
+  location ~ ^/([^\.]+)$ {
+    try_files /$1.html =404;
+  }
+
+  # Make /pricing/ look for /site/public/pricing/index.html
+  location / {
+    index index.html;
+  }
+}

data/lib/skiff/templates/dotfiles/dockerignore

@@ -0,0 +1,2 @@
+# Ignore env file
+/.env

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

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

data/lib/skiff/templates/dotfiles/gitignore

@@ -0,0 +1,2 @@
+# Ignore env file
+/.env

data/lib/skiff/templates/public/_errors/404.html

@@ -0,0 +1,6 @@
+<!--# set var="title" value="404: Not Found" -->
+<!--# include file="/_includes/header.html" -->
+
+<h1>404: Not Found!</h1>
+
+<!--# include file="/_includes/footer.html" -->

data/lib/skiff/templates/public/_includes/footer.html

@@ -0,0 +1,2 @@
+</body>
+</html>

data/lib/skiff/templates/public/_includes/header.html

@@ -0,0 +1,5 @@
+<html>
+<head>
+  <title><!--# echo var="title" --></title>
+</head>
+<body>

data/lib/skiff/templates/public/index.html

@@ -0,0 +1,6 @@
+<!--# set var="title" value="Skiff site" -->
+<!--# include file="/_includes/header.html" -->
+
+<h1>O'hoy!</h1>
+
+<!--# include file="/_includes/footer.html" -->

data/lib/skiff/templates/public/up.html

@@ -0,0 +1,7 @@
+<html>
+<head>
+<title>Up</title>
+</head>
+<body style="background-color: green;">
+</body>
+</html>

data/lib/skiff/templates/serve

@@ -0,0 +1,16 @@
+#!/bin/bash
+set -e
+
+polling_pull() {
+  while true; do
+    echo "Pulling latest..."
+    git pull $GIT_URL $GIT_BRANCH || true
+    sleep 10
+  done
+}
+
+# When GIT_URL is set start polling in the background
+[[ "$GIT_URL" ]] && polling_pull &
+
+# Start NGINX in the foreground
+nginx -g 'daemon off;'

data/lib/skiff/templates/site.rb

@@ -0,0 +1,19 @@
+template  "dotfiles/env.tt", ".env"
+copy_file "dotfiles/gitignore", ".gitignore"
+copy_file "dotfiles/dockerignore", ".dockerignore"
+
+empty_directory "config"
+template  "config/deploy.yml.tt", "config/deploy.yml"
+copy_file "config/deploy.staging.yml", "config/deploy.staging.yml"
+copy_file "config/server.conf", "config/server.conf"
+
+directory "public"
+empty_directory_with_keep_file "public/assets/images"
+empty_directory_with_keep_file "public/assets/javascripts"
+empty_directory_with_keep_file "public/assets/stylesheets"
+
+copy_file "Dockerfile"
+template "README.md.tt", "README.md"
+
+copy_file "serve"
+chmod "serve", 0755, verbose: false

data/lib/skiff/version.rb

@@ -0,0 +1,3 @@
+module Skiff
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification
+name: kamal-skiff
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- David Heinemeier Hansson
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-10-23 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'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email: dhh@hey.com
+executables:
+- skiff
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- bin/skiff
+- lib/kamal-skiff.rb
+- lib/skiff/cli.rb
+- lib/skiff/templates/Dockerfile
+- lib/skiff/templates/README.md.tt
+- lib/skiff/templates/config/deploy.staging.yml
+- 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/public/_errors/404.html
+- lib/skiff/templates/public/_includes/footer.html
+- lib/skiff/templates/public/_includes/header.html
+- lib/skiff/templates/public/index.html
+- lib/skiff/templates/public/up.html
+- lib/skiff/templates/serve
+- lib/skiff/templates/site.rb
+- lib/skiff/version.rb
+homepage: https://github.com/basecamp/kamal-skiff
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Deploy static sites using nginx + SSI with Kamal.
+test_files: []