kamal-ui

kamal-ui is a local-first web dashboard for operating Rails applications that are deployed with Kamal. It lets an operator load a local Kamal project, inspect prerequisites, run common Kamal commands, review command output, check containers, view logs, sample server health, and prepare rollbacks from a browser.

This project is maintained at KernelTheory/kamal-ui.

Status

This is early open-source software. Expect the interface and internal APIs to change while the core workflows settle.

The app is intentionally unauthenticated because it is designed to run on a trusted local machine. Do not expose it directly to the public internet. If you deploy it anywhere reachable by other people, put it behind a private network, VPN, reverse proxy authentication, or another access-control layer.

Requirements

• Ruby 3.4.2
• Bundler
• SQLite 3
• Docker, when building or deploying the app container
• A target application that already uses Kamal
• Kamal 2.12.0 or newer in the target application
• A target app config/deploy.yml or deploy.yml
• A target app .kamal/secrets file before running deploy-related commands

Setup

Clone the repository:

git clone https://github.com/KernelTheory/kamal-ui.git
cd kamal-ui

Install dependencies, prepare the database, clear old logs/temp files, and start the app:

bin/setup

If you only want to prepare the app without starting the server:

bin/setup --skip-server

Start the development server later with:

bin/dev

Then open http://localhost:3000.

Local Usage

1. Start kamal-ui with bin/dev.
2. Open http://localhost:3000.
3. Choose a local application directory that contains Kamal configuration.
4. Confirm the prerequisite checks for Kamal, Docker, Git metadata, and .kamal/secrets.
5. Use the dashboard to run supported commands such as deploy, redeploy, setup, rollback, logs, container status, and server health checks.

Commands run from the selected target app directory, not from the kamal-ui repository. That target app must have its own dependencies, Kamal config, credentials, and deployment access ready.

Common Commands

Install or update dependencies:

bundle install

Prepare the database:

bin/rails db:prepare

Run the Rails test suite:

bin/rails test

Run the full local CI workflow:

bin/ci

Run individual quality checks:

bin/rubocop
bin/bundler-audit
bin/importmap audit
bin/brakeman --quiet --no-pager --exit-on-warn --exit-on-error

Open a Rails console:

bin/rails console

Reset local development data:

bin/setup --reset --skip-server

Architecture

kamal-ui is a Rails 8 application using:

• SQLite for local persistence
• Solid Queue, Solid Cache, and Solid Cable
• Turbo and Stimulus through import maps
• Propshaft for assets
• Kamal command wrappers under app/services/kamal
• Controller and service tests under test

Key directories:

• app/controllers: HTTP endpoints for dashboard, projects, commands, logs, containers, server health, and rollbacks
• app/services/kamal: command building, command execution, log parsing, health sampling, rollback discovery, and container inspection
• app/jobs: background jobs for command execution and sampling
• app/views: Rails templates for the UI
• app/assets/stylesheets/application.css: application styling
• lib/docs: planning notes, design documentation, and implementation records
• test: Minitest coverage for models, services, jobs, controllers, and stylesheets

Deployment

Most users should run kamal-ui locally. Deployment is optional and should be treated as an operator-facing internal tool deployment.

Before deploying:

1. Run bin/ci locally and make sure it passes.
2. Decide how access will be restricted. The app does not provide built-in authentication.
3. Set up the production Rails secret, normally through RAILS_MASTER_KEY or equivalent secret management.
4. Configure persistent storage for SQLite databases and command logs. Do not rely on ephemeral container storage for production-like use.
5. Confirm the host can reach any target app repositories, Docker registries, and servers that operators need to manage.
6. Confirm Docker and Kamal are available where commands need to execute.
7. Review backup and restore expectations for SQLite data and generated logs.
8. Review Dockerfile and bin/docker-entrypoint for the current container boot behavior.

Build and run the production container manually:

docker build -t kamal_ui .
docker run -d -p 80:80 -e RAILS_MASTER_KEY=<value> --name kamal_ui kamal_ui

When deploying with Kamal, create deployment configuration for this repository in the usual Kamal format and keep secrets out of Git. Protect the deployed app with network or proxy-level access control.

Contributing

Contributions are welcome through pull requests.

Before starting:

1. Open or find an issue that describes the problem, unless the change is small and obvious.
2. Keep changes focused. Separate refactors from behavior changes.
3. For UI work, read lib/docs/design.md before changing templates or CSS.
4. For behavior changes, add or update tests first.

Development process:

1. Create a branch from main.
2. Run bin/setup --skip-server.
3. Add one small behavior at a time.
4. Run the smallest relevant test while developing.
5. Run bin/ci before opening a PR.
6. Update documentation when behavior, setup, commands, or operator expectations change.

Pull request checklist:

• Describe the user-facing change and why it is needed.
• Link the related issue or discussion when one exists.
• Include screenshots for UI changes.
• Include test output, preferably bin/ci.
• Call out any deployment, security, data migration, or compatibility risks.
• Keep generated files, local logs, temporary scripts, and machine-specific files out of the PR.

Instructions For Bot Agents

Bot agents are welcome to contribute, but they should behave like careful maintainers:

• Read this README and AGENTS.md before changing files.
• Inspect the existing code and tests before proposing edits.
• Prefer small, reviewable changes with clear test coverage.
• Follow the local Rails and Minitest patterns already in the repository.
• Do not introduce new frameworks, package managers, services, or build tools without a strong reason and maintainer approval.
• For UI changes, follow lib/docs/design.md and verify rendered states with screenshots.
• Do not weaken, delete, or skip tests to make a change pass.
• Do not expose secrets, credentials, local paths, command logs with sensitive output, or .kamal/secrets.
• Leave unrelated user or maintainer changes untouched.
• Report commands run and any tests that could not be run.

Security

This project shells out to Kamal commands for selected local projects. Treat it as an operator tool with access to deployment credentials and production infrastructure.

Do not expose a running instance publicly without an external access-control layer. Do not commit .kamal/secrets, Rails master keys, registry credentials, SSH keys, command logs containing secrets, or production database files.

License

This project is released under the terms in LICENSE.