Add a runnable example compose stack for WarpEngine

examples/compose boots everything the engine's workflow assumes: mysql, a
minimal Rails host consuming the engine as a path gem, an SSH drop area
sharing the softwares volume with the app, and — behind the ci profile —
gitea plus woodpecker (agent attached to the stack network so pipeline
steps reach droparea/app by service name).

host_app doubles as a reference for a brand-new host: Gemfile, the two
initializers, apipie + engine mounts in routes.rb; on first boot the
entrypoint runs the install generator and db:prepare.

The README gains a detailed bring-up walkthrough: quickstart, publishing
a release by hand over scp + /update (verified end to end from a clean
slate), and the full gitea/woodpecker OAuth wiring.

examples/compose/host_app/.gitignore

@@ -0,0 +1,6 @@
+# Generated on first boot by the entrypoint (install generator + db:prepare).
+db/migrate/
+db/schema.rb
+log/
+tmp/
+Gemfile.lock

examples/compose/host_app/Dockerfile

@@ -0,0 +1,20 @@
+FROM ruby:3.3-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  build-essential \
+  default-libmysqlclient-dev \
+  git \
+  tzdata \
+  libyaml-dev \
+  pkg-config \
+  && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# The app source, the engine checkout (/warp_engine) and the bundle are all
+# mounted at runtime by the compose file; the entrypoint bundles on first boot.
+ENTRYPOINT ["./bin/docker-entrypoint"]
+
+EXPOSE 3000
+
+CMD ["bin/rails", "server", "-b", "0.0.0.0", "-p", "3000"]

examples/compose/host_app/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+gem "rails", "~> 8.0.0"
+gem "mysql2", "~> 0.5"
+gem "puma"
+
+# In this example stack the engine comes straight from the repo checkout the
+# compose file mounts at /warp_engine. A real host would use the git source or
+# the Forgejo rubygems registry instead — see the engine README.
+gem "warp_engine", path: ENV.fetch("WARP_ENGINE_PATH", "/warp_engine")

examples/compose/host_app/Rakefile

@@ -0,0 +1,3 @@
+require_relative "config/application"
+
+Rails.application.load_tasks

examples/compose/host_app/bin/docker-entrypoint

@@ -0,0 +1,16 @@
+#!/bin/sh
+set -e
+
+bundle check || bundle install
+
+# First boot: run the install generator the way a real host would. It creates
+# the create_warp_engine_tables migration; --skip leaves our initializer alone.
+if ! ls db/migrate/*create_warp_engine_tables* >/dev/null 2>&1; then
+  bin/rails generate warp_engine:install --skip
+fi
+
+bin/rails db:prepare
+
+rm -f tmp/pids/server.pid
+
+exec "$@"

examples/compose/host_app/bin/rails

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+APP_PATH = File.expand_path("../config/application", __dir__)
+require_relative "../config/boot"
+require "rails/commands"

examples/compose/host_app/config.ru

@@ -0,0 +1,4 @@
+require_relative "config/environment"
+
+run Rails.application
+Rails.application.load_server

examples/compose/host_app/config/application.rb

@@ -0,0 +1,23 @@
+require_relative "boot"
+
+require "rails"
+require "active_model/railtie"
+require "active_record/railtie"
+require "action_controller/railtie"
+require "action_view/railtie"
+require "action_dispatch/railtie"
+
+Bundler.require(*Rails.groups)
+require "warp_engine"
+
+module HostApp
+  class Application < Rails::Application
+    config.load_defaults 8.0
+
+    config.time_zone = "UTC"
+    config.active_record.default_timezone = :utc
+
+    # Demo stack: reachable as localhost, gitea-network hostnames, etc.
+    config.hosts.clear
+  end
+end

examples/compose/host_app/config/boot.rb

@@ -0,0 +1,3 @@
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+require "bundler/setup"

examples/compose/host_app/config/database.yml

@@ -0,0 +1,8 @@
+development:
+  adapter: mysql2
+  encoding: utf8mb4
+  username: root
+  password: <%= ENV.fetch("MYSQL_ROOT_PASSWORD", "warpengine") %>
+  host: mysql
+  port: 3306
+  database: warp_engine_example

examples/compose/host_app/config/environment.rb

@@ -0,0 +1,3 @@
+require_relative "application"
+
+Rails.application.initialize!

examples/compose/host_app/config/environments/development.rb

@@ -0,0 +1,10 @@
+Rails.application.configure do
+  config.enable_reloading = true
+  config.eager_load = false
+  config.consider_all_requests_local = true
+
+  config.active_record.migration_error = :page_load
+  config.active_record.verbose_query_logs = true
+
+  config.logger = ActiveSupport::Logger.new($stdout)
+end

examples/compose/host_app/config/initializers/apipie.rb

@@ -0,0 +1,11 @@
+Apipie.configure do |config|
+  config.app_name = "WarpEngine Example Host"
+  config.api_base_url = ""
+  config.doc_base_url = "/api/docs"
+  config.api_controllers_matcher = [
+    "#{WarpEngine::Engine.root}/app/controllers/**/*.rb"
+  ]
+  config.validate = false
+  config.translate = false
+  config.default_version = "1.0"
+end

examples/compose/host_app/config/initializers/warp_engine.rb

@@ -0,0 +1,9 @@
+Rails.application.config.to_prepare do
+  WarpEngine.configure do |c|
+    c.file_container_path  = ENV.fetch("FILE_CONTAINER_PATH", "/softwares")
+    c.image_container_path = ENV.fetch("IMAGE_CONTAINER_PATH", "/images")
+
+    # Beállítatlan secret esetén a /update endpoint minden kérést elutasít.
+    c.update_secret = ENV["UPDATE_SECRET"]
+  end
+end

examples/compose/host_app/config/routes.rb

@@ -0,0 +1,6 @@
+Rails.application.routes.draw do
+  apipie
+
+  # Keep the engine mount the last entry so the host's own routes win.
+  mount WarpEngine::Engine => "/"
+end