kitsune-kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 57456c12dd12944d84cfd91365faf9997f14b6612ac9530e0d59612a2127f7c3
+  data.tar.gz: 171c5324395c519e83c3ee95dc1fb301a93813113e3b95a01129c905be634525
+SHA512:
+  metadata.gz: 3aff57085a3a9d071c183a2d8ebfda9fd729f6a1ea6da7dc38436aaefca10e3d24001c6cdd6ae4aa8a76c71b7448f6b180724e3ed7014974c58c57bb9cb81eca
+  data.tar.gz: c767d70f51be75dd80b6d8f111afb8d3c89fea9074337ff7df5eb66c83b96526ab52f4ac184988c5b28d9772ced5c9f67637467a94808f86b26f0fc26a57fbaf

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## [0.1.0] - 2025-04-29
+### Added
+- First public release
+- Bootstrap commands for DigitalOcean + Docker + PostgreSQL

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Omar Herrera
+
+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,192 @@
+# Kitsune Kit 🦊
+
+<p align="center">
+   <img src="kitsune-kit-logo.jpg" alt="Kitsune Logo" width="180"/>
+</p>
+
+**Kitsune Kit** is a Ruby gem that automates the provisioning, configuration, and setup of remote Linux servers (VPS) to host applications deployed with [Kamal](https://github.com/basecamp/kamal) or Docker Compose. It is designed to work on DigitalOcean infrastructure (for now), featuring reversible commands and a clear workflow.
+
+> 🛠️ *Ideal for Ruby developers who want to launch production without relying on other services.*
+
+---
+
+## 🔍 Main Features
+
+- 🧪 **Automatically provisions** a Droplet on DigitalOcean
+- 👤 Configures a secure, passwordless `deploy` user
+- 🔐 Applies firewall rules (UFW) for SSH, HTTP, HTTPS
+- ♻️ Enables automatic security updates (unattended-upgrades)
+- 🐳 Installs and configures Docker Engine and private networking
+- 🐘 Deploys PostgreSQL via Docker Compose with healthcheck and `.env`
+- 🔄 All steps can be rolled back (`--rollback`)
+- ⚡ Fast, reproducible and without relying on YAML or complex external tools
+
+---
+
+## 📦 Installation
+
+Add this line to your `Gemfile`:
+
+```ruby
+gem "kitsune-kit"
+```
+
+Or install it manually:
+
+```bash
+gem install kitsune-kit
+```
+
+---
+
+## ⚙️ Prerequisites
+
+1. Configure a DigitalOcean API token:
+    ```bash
+    export DO_API_TOKEN="your_token"
+    ```
+
+2. Have the SSH key ID uploaded to DigitalOcean:
+    ```bash
+    export SSH_KEY_ID="123456"
+    ```
+
+3. Have the private key installed on your local machine:
+    ```bash
+    export SSH_KEY_PATH="~/.ssh/id_rsa"
+    ```
+
+---
+
+## 🚀 Getting Started
+
+Initialize the Kitsune project structure:
+
+```bash
+kit init
+```
+
+This will create the `.kitsune/` directory, multiple `.env` files, and the necessary Docker templates. Run it in your project's root directory.
+
+---
+
+## 🔧 Main Commands
+
+### 🧱 Server Provisioning
+
+```bash
+kit bootstrap execute
+```
+
+This creates a Droplet and executes:
+
+1. `setup_user create`
+2. `setup_firewall create`
+3. `setup_unattended create`
+
+### 🐳 Full Docker Installation
+
+```bash
+kit bootstrap_docker execute --server-ip 123.123.123.123
+```
+
+This applies in order:
+
+1. `setup_docker_prereqs create`
+2. `install_docker_engine create`
+3. `postinstall_docker create`
+
+### 🐘 Install PostgreSQL with Docker Compose
+
+```bash
+kit setup_postgres_docker create --server-ip 123.123.123.123
+```
+
+It will provide you with a `DATABASE_URL` ready for Rails or any other app.
+
+---
+
+## ♻️ Rollback for Each Step
+
+Each command accepts the `--rollback` flag. For example:
+
+```bash
+kit bootstrap execute --rollback --keep-server
+```
+
+This:
+- Reverts the server configuration (`unattended`, `firewall`, `user`)
+- Optionally **deletes the Droplet** (if you don't use `--keep-server`)
+
+The same applies to any other subcommand, such as:
+
+```bash
+kit bootstrap_docker execute --rollback --server-ip ...
+kit setup_postgres_docker rollback --server-ip ...
+```
+
+---
+
+## 🌎 Support for Multiple Environments
+
+Use `switch_env` to change between environments:
+
+```bash
+kit switch_env to production
+```
+
+This updates `.kitsune/kit.env` and creates (if it doesn't exist) `.kitsune/infra.production.env`.
+
+---
+
+## 🔗 Integration with Kamal
+
+Once the server is configured:
+
+1. Define your `kamal.yml` pointing to the created droplet
+2. Run `kamal setup` to initialize the deployment
+3. Use `kamal deploy` as usual
+
+---
+
+## 💡 Tips
+
+- Use `kit init` in every new project.
+- Customize `.kitsune/docker/postgres.yml` if you need additional services.
+
+---
+
+## 📘 Quick Example
+
+```bash
+# Initialize project structure
+kit init
+
+# Provision Droplet and configure everything
+kit bootstrap execute
+
+# Install Docker
+kit bootstrap_docker execute --server-ip 123.123.123.123
+
+# Set up the database
+kit setup_postgres_docker create --server-ip 123.123.123.123
+```
+
+---
+
+## 🧪 In Development
+
+- [ ] Support for other providers (Hetzner)
+- [ ] Create databases on another server
+
+---
+
+## 🔐 Security
+
+Never upload your `.env` files to public repositories. Kitsune does not encrypt them: it assumes you control your machine and your repo. Add `.kitsune/` to your project's `.gitignore`.
+
+---
+
+## 📄 License
+
+MIT License © [Omar Herrera / OmarHrra]

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/kit

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+require "bundler/setup"
+require "dotenv/load"
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "kitsune/kit"
+require "kitsune/kit/cli"
+
+Kitsune::Kit::CLI.start(ARGV)

data/lib/kitsune/blueprints/.env.template

@@ -0,0 +1,17 @@
+# DigitalOcean Droplet defaults
+DO_API_TOKEN=
+DROPLET_NAME=
+REGION=
+SIZE=
+IMAGE=
+SSH_KEY_ID=
+TAG_NAME=
+
+# SSH configuration
+SSH_KEY_PATH=
+# SSH_PORT=22 (optional)
+
+# PostgreSQL Docker defaults
+POSTGRES_DB=
+POSTGRES_USER=
+POSTGRES_PASSWORD=

data/lib/kitsune/blueprints/docker/postgres.yml

@@ -0,0 +1,20 @@
+services:
+  postgres:
+    image: postgres:17
+    restart: always
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB}
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER}"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+
+volumes:
+  pgdata:

data/lib/kitsune/blueprints/kit.env.template

@@ -0,0 +1 @@
+KIT_ENV=development

data/lib/kitsune/kit/cli.rb

@@ -0,0 +1,64 @@
+require "thor"
+require_relative "env_loader"
+require_relative "commands/init"
+require_relative "commands/switch_env"
+require_relative "commands/provision"
+require_relative "commands/setup_user"
+require_relative "commands/setup_firewall"
+require_relative "commands/setup_unattended"
+require_relative "commands/bootstrap"
+require_relative "commands/setup_docker_prereqs"
+require_relative "commands/install_docker_engine"
+require_relative "commands/postinstall_docker"
+require_relative "commands/bootstrap_docker"
+require_relative "commands/setup_postgres_docker"
+
+module Kitsune
+  module Kit
+    class CLI < Thor
+      def self.dispatch(m, args, options, config)
+        unless ["init", "switch_env", "help", nil].include?(args.first)
+          Kitsune::Kit::EnvLoader.load!
+        end
+
+        super
+      end
+
+      desc "init", "Initialize Kitsune Kit project structure"
+      subcommand "init", Kitsune::Kit::Commands::Init
+
+      desc "switch_env SUBCOMMAND", "Switch the active Kitsune environment"
+      subcommand "switch_env", Kitsune::Kit::Commands::SwitchEnv
+
+      desc "provision SUBCOMMAND", "Provisioning tasks"
+      subcommand "provision", Kitsune::Kit::Commands::Provision
+
+      desc "setup_user SUBCOMMAND", "Create or rollback deploy user on remote server"
+      subcommand "setup_user", Kitsune::Kit::Commands::SetupUser
+
+      desc "setup_firewall SUBCOMMAND", "Configure or rollback UFW firewall rules"
+      subcommand "setup_firewall", Kitsune::Kit::Commands::SetupFirewall
+
+      desc "setup_unattended SUBCOMMAND", "Configure or rollback unattended-upgrades"
+      subcommand "setup_unattended", Kitsune::Kit::Commands::SetupUnattended
+
+      desc "bootstrap SUBCOMMAND", "Run full server setup or rollback"
+      subcommand "bootstrap", Kitsune::Kit::Commands::Bootstrap
+
+      desc "setup_docker_prereqs SUBCOMMAND", "Install or rollback docker prerequisites"
+      subcommand "setup_docker_prereqs", Kitsune::Kit::Commands::SetupDockerPrereqs
+
+      desc "install_docker_engine SUBCOMMAND", "Install or rollback Docker Engine"
+      subcommand "install_docker_engine", Kitsune::Kit::Commands::InstallDockerEngine
+
+      desc "postinstall_docker SUBCOMMAND", "Apply or rollback Docker post-installation tasks"
+      subcommand "postinstall_docker", Kitsune::Kit::Commands::PostinstallDocker
+
+      desc "bootstrap_docker SUBCOMMAND", "Run full docker setup or rollback"
+      subcommand "bootstrap_docker", Kitsune::Kit::Commands::BootstrapDocker
+
+      desc "setup_postgres_docker SUBCOMMAND", "Setup PostgreSQL via Docker Compose on remote server"
+      subcommand "setup_postgres_docker", Kitsune::Kit::Commands::SetupPostgresDocker
+    end
+  end
+end

data/lib/kitsune/kit/commands/bootstrap.rb

@@ -0,0 +1,118 @@
+require "thor"
+require "open3"
+require_relative "../defaults"
+require_relative "../options_builder"
+require_relative "../provisioner"
+
+module Kitsune
+  module Kit
+    module Commands
+      class Bootstrap < Thor
+        namespace "bootstrap"
+
+        class_option :rollback, type: :boolean, default: false, desc: "Rollback the setup"
+        class_option :keep_server, type: :boolean, default: false, desc: "Keep server after rollback"
+        class_option :ssh_port, type: :string, desc: "SSH port for server"
+        class_option :ssh_key_path, type: :string, desc: "SSH private key path"
+
+        desc "execute", "Run the full bootstrap process or rollback"
+        def execute
+          filled_options = Kitsune::Kit::OptionsBuilder.build(
+            options,
+            defaults: Kitsune::Kit::Defaults.ssh
+          )
+
+          if filled_options[:rollback]
+            say "🔄 Rolling back server configurations...", :yellow
+            rollback_sequence(filled_options)
+          else
+            say "🏗️ Setting up server from scratch...", :green
+            setup_sequence(filled_options)
+          end
+
+          say "🎉 Done!", :green
+        end
+
+        no_commands do
+          def setup_sequence(filled_options)
+            droplet_ip = fetch_droplet_ip
+
+            say "→ Droplet IP: #{droplet_ip}", :cyan
+
+            run_cli("setup_user create", droplet_ip, filled_options)
+            run_cli("setup_firewall create", droplet_ip, filled_options)
+            run_cli("setup_unattended create", droplet_ip, filled_options)
+          end
+
+          def rollback_sequence(filled_options)
+            provision_options = Kitsune::Kit::OptionsBuilder.build(
+              {},
+              defaults: Kitsune::Kit::Defaults::infra
+            )
+
+            provisioner = Kitsune::Kit::Provisioner.new(provision_options)
+
+            if (droplet = provisioner.find_droplet).nil?
+              say "💡 Nothing to rollback.", :green
+              return
+            end
+
+            droplet_ip = provisioner.send(:public_ip, droplet)
+            say "→ Using Droplet IP: #{droplet_ip}", :cyan
+
+            if ssh_accessible?(droplet_ip, filled_options)
+              run_cli("setup_unattended rollback", droplet_ip, filled_options)
+              run_cli("setup_firewall rollback", droplet_ip, filled_options)
+            else
+              say "⏭️  Skipping unattended-upgrades and firewall rollback (no deploy user)", :yellow
+            end
+
+            run_cli("setup_user rollback", droplet_ip, filled_options)
+
+            unless filled_options[:keep_server]
+              say "▶️ Running: kitsune kit provision rollback", :blue
+              Kitsune::Kit::CLI.start(%w[provision rollback])
+            else
+              say "⏭️  Skipping droplet deletion (--keep-server enabled)", :yellow
+            end
+          end
+
+          def fetch_droplet_ip
+            output, status = Open3.capture2e("bin/kit provision create")
+            unless status.success?
+              abort "❌ Error fetching or creating droplet"
+            end
+
+            ip = output.match(/(\d{1,3}\.){3}\d{1,3}/).to_s
+            abort "❌ Could not detect droplet IP!" if ip.empty?
+            ip
+          end
+
+          def run_cli(command, droplet_ip, filled_options)
+            say "▶️ Running: kitsune kit #{command} --server-ip #{droplet_ip}", :blue
+            subcommand, action = command.split(" ", 2)
+            Kitsune::Kit::CLI.start([
+              subcommand, action,
+              "--server-ip", droplet_ip,
+              "--ssh-port", filled_options[:ssh_port],
+              "--ssh-key-path", filled_options[:ssh_key_path]
+            ])
+          rescue SystemExit => e
+            abort "❌ Command failed: #{command} (exit #{e.status})"
+          end
+
+          def ssh_accessible?(droplet_ip, filled_options)
+            system(
+              "ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new " \
+              "-p #{filled_options[:ssh_port]} " \
+              "-i #{File.expand_path(filled_options[:ssh_key_path])} " \
+              "deploy@#{droplet_ip} true",
+              out: File::NULL,
+              err: File::NULL
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/commands/bootstrap_docker.rb

@@ -0,0 +1,66 @@
+require "thor"
+require "open3"
+require_relative "../defaults"
+require_relative "../options_builder"
+
+module Kitsune
+  module Kit
+    module Commands
+      class BootstrapDocker < Thor
+        namespace "bootstrap_docker"
+
+        class_option :server_ip,    aliases: "-s", required: true, desc: "Server IP address or hostname"
+        class_option :ssh_port,     aliases: "-p", desc: "SSH port for server"
+        class_option :ssh_key_path, aliases: "-k", desc: "SSH private key path"
+        class_option :rollback,     type: :boolean, default: false, desc: "Rollback Docker setup steps"
+
+        desc "execute", "Run full Docker setup or rollback sequence"
+        def execute
+          filled_options = Kitsune::Kit::OptionsBuilder.build(
+            options,
+            required: [:server_ip],
+            defaults: Kitsune::Kit::Defaults.ssh
+          )
+
+          if filled_options[:rollback]
+            say "🔄 Rolling back full Docker setup...", :yellow
+            rollback_sequence(filled_options)
+          else
+            say "🐳 Running full Docker setup...", :green
+            setup_sequence(filled_options)
+          end
+
+          say "🎉 Done!", :green
+        end
+
+        no_commands do
+          def setup_sequence(filled_options)
+            run_cli("setup_docker_prereqs create", filled_options)
+            run_cli("install_docker_engine create", filled_options)
+            run_cli("postinstall_docker create", filled_options)
+          end
+
+          def rollback_sequence(filled_options)
+            run_cli("postinstall_docker rollback", filled_options)
+            run_cli("install_docker_engine rollback", filled_options)
+            run_cli("setup_docker_prereqs rollback", filled_options)
+          end
+
+          def run_cli(command, filled_options)
+            say "▶️ Running: kitsune kit #{command} --server-ip #{filled_options[:server_ip]}", :blue
+
+            subcommand, action = command.split(" ", 2)
+            Kitsune::Kit::CLI.start([
+              subcommand, action,
+              "--server-ip", filled_options[:server_ip],
+              "--ssh-port",  filled_options[:ssh_port],
+              "--ssh-key-path", filled_options[:ssh_key_path]
+            ])
+          rescue SystemExit => e
+            abort "❌ Command failed: #{command} (exit #{e.status})"
+          end
+        end
+      end
+    end
+  end
+end