Toolbox: Simple automation for a Mac-based home web server

A lightweight framework for running multiple web apps on a Mac Mini (or, any Mac). This is the actual script that powers www.contraption.co and other web applications from a single Mac Mini home server. Learn more about the story in "A mini data center".

If you encounter any problems, please open an issue.

What is this?

Toolbox is a collection of Ruby scripts that orchestrate Docker containers, Git repositories, and system services to create a robust home server environment. It's designed to be simple, maintainable, and reliable - perfect for hosting personal web apps from home without complex infrastructure or monthly cloud costs.

For full setup instructions, read the post: How to host web apps on a Mac Mini

Philosophy

This toolbox is built with the following principles in mind:

Simplicity over complexity: Scripts are readable and maintainable
Docker-based: Each service runs in its own container
Git-powered: Auto-deployment from repositories
Configuration over code: Centralized configuration in one file
Secure access: Cloudflare Tunnel eliminates the need to open ports
Secret management: 1Password integration keeps credentials secure
Legibility: No frameworks, minimal learning curve, and mostly raw Docker

Features

Automatic service management: Start/restart services on boot
Cloudflare Tunnel integration: Expose services to the internet securely
Git repository management: Auto-update when changes are detected
Docker container orchestration: Simplified management of containerized apps
One-password integration: Secure credential management
Heartbeat monitoring: Optional uptime monitoring
Lock screen on boot: Secure your server with automatic screen locking after reboot
Complex Git Service Management: Supports services requiring initial setup scripts and managed via their own Docker Compose.

Requirements

For full setup instructions, read: How to host web apps on a Mac Mini

Before you start, ensure you have:

A Mac running macOS (tested on Monterey and later)
Homebrew installed
Docker Desktop installed and running
Git installed and configured with access to your repositories
ASDF for Ruby version management
1Password CLI installed and configured
Cloudflare account with a domain
Cloudflare Tunnel configured
(Optional) UptimeRobot account for monitoring
(Optional) Papertrail account for log aggregation

Quick start

Fork this repository
Clone your fork to your Mac
Configure your Cloudflare tunnel in config.yml
Edit config.rb to match your services and domains
Install Ruby: asdf install
Run: ruby toolbox.rb
Set up the heartbeat script for auto-updates

Setting up 1Password CLI

The toolbox relies on 1Password CLI for secure credential storage:

Install 1Password CLI:
```
brew install 1password-cli
```
Security Recommendation: Create a dedicated vault in 1Password specifically for your server credentials. This limits the scope of access to only the secrets needed for this toolbox, keeping your personal secrets separate.
Choose an authentication method:

For manual use:
- Sign in to your 1Password account interactively:
```
eval $(op signin)
```
For automated use (recommended for the heartbeat service):
- Create a service account token:
  - Go to 1Password account settings → Developer → Service Accounts
  - Create a new service account token with access only to your dedicated server vault
  - Add the token to the LaunchAgent plist file (no interactive login required)

For detailed setup instructions, follow the official 1Password CLI guide.

Setting up Cloudflare Tunnel

Cloudflare Tunnel provides a secure way to expose your home server to the internet without opening ports. For a detailed guide on setting up Cloudflare Tunnel on a Mac, follow Sam Rhea's excellent guide.

To set up Cloudflare Tunnel for this toolbox:

Create a Cloudflare account and add your domain
Install cloudflared: brew install cloudflared
Authenticate with Cloudflare: cloudflared tunnel login
Create a tunnel: cloudflared tunnel create toolbox

Create a config.yml file in your toolbox directory with your host-to-port mappings:

tunnel: YOUR_TUNNEL_ID
credentials-file: /path/to/credentials/file.json

ingress:
  - hostname: yourapp.yourdomain.com
    service: http://localhost:8000
  - hostname: anotherapp.yourdomain.com
    service: http://localhost:4000
  - service: http_status:404

Update the TUNNEL_CONFIG section in config.rb to reference your config.yml file

The toolbox will manage starting and running your Cloudflare Tunnel using this configuration.

Configuring your services

Edit config.rb to match your services and domains
Configure your Docker services, Git repositories, and system services in the corresponding sections
Update the Cloudflare Tunnel configuration to reference your config.yml file
Each service requires its own configuration

Here's an example of how services are defined in config.rb:

DOCKER_SERVICES = [
  {
    name: 'ghost',
    image: 'ghost:5.109.2',
    ports: ['2368:2368'],
    volumes: ["#{DATA_DIR}/ghost:/var/lib/ghost/content"],
    environment: {
      url: 'https://your-domain.com',
      # Other environment variables...
    }
  }
]

Here's an example of a service cloned from Git that runs its own install script and is managed by Docker Compose within its directory:

GIT_SERVICES = [
  {
    name: 'sentry',                                         # Service name
    repo_url: 'https://github.com/getsentry/self-hosted.git', # Sentry repo URL
    local_path: "#{Config::CODE_DIR}/sentry-self-hosted",   # Local path for the repo
    # Command to run ONCE after initial clone.
    install_cmd: './install.sh --no-report-self-hosted-issues',
    # Indicates this service uses docker-compose in its directory
    use_compose: true,
    # Auto-update set to false as Sentry upgrades involve install script, not just git pull
    auto_update: false
  }
]

Heartbeat script (auto-updates)

To keep your server updated automatically:

Run the installation script: ruby install_launch_agent.rb

Edit the generated plist file:

vi ~/Library/LaunchAgents/co.contraption.toolbox.heartbeat.plist

Configure the plist file:
- Set your 1Password service account token in the OP_SERVICE_ACCOUNT_TOKEN field
- Update other paths if necessary
Load the LaunchAgent: launchctl load ~/Library/LaunchAgents/co.contraption.toolbox.heartbeat.plist

The script will check for updates every minute and apply them if found.

Security: Automatic screen locking

Included in the repository is a lock_screen_on_login.app utility that automatically locks your Mac's screen upon login. This is useful for servers configured with automatic login (to ensure services start on reboot) while still protecting physical access to the machine.

To set up automatic screen locking:

Add lock_screen_on_login.app to your Login Items:
- Open System Preferences/Settings → Users & Groups → Login Items
- Click the "+" button and select the lock_screen_on_login.app from the repository
- This ensures the screen locks immediately after automatic login

This setup allows your server to reboot and start services automatically without requiring manual login, while still ensuring that anyone with physical access to the machine needs a password to use it.

Configuring log forwarding (optional)

If you want to forward logs to a service like Papertrail:

Create a Papertrail account and set up a log destination
Run the installation script: ruby install_papertrail.rb
Follow the on-screen instructions to complete the setup
Update the generated log_files.yml configuration file with your Papertrail host and port

The script will:

Create a LaunchDaemon plist file for remote_syslog
Generate a sample log configuration if one doesn't exist
Provide commands to finalize the installation

For manual installation instead:

Install the remote_syslog tool:
```
brew install remote_syslog
```

Configure the LaunchDaemon:

sudo cp com.papertrailapp.remote_syslog.plist /Library/LaunchDaemons/
sudo vi /Library/LaunchDaemons/com.papertrailapp.remote_syslog.plist

Load the LaunchDaemon:

sudo launchctl load /Library/LaunchDaemons/com.papertrailapp.remote_syslog.plist

Key services

Docker containers

All web applications run in Docker containers, making them isolated and easy to manage. The toolbox handles:

Container creation and configuration
Automatic updates when new images are available
Network configuration
Volume management for persistent data

Cloudflare Tunnel

Cloudflare Tunnel creates a secure connection between your Mac and Cloudflare's edge network:

No need to open ports on your router
SSL termination and DDoS protection
Access control with Cloudflare Access (optional)
Custom domain support

Git repositories

For apps that require custom builds:

Automatic cloning and updating
Build process management
Deployment to containers or directories
Support for private repos (requires GitHub authentication)
Can handle complex setups involving initial installation scripts and integrated Docker Compose management.

Customizing for your needs

This is a personal tool that I use for my own server - you'll need to adapt it:

Remove services you don't need (Ghost, Plausible, etc.)
Add your own applications to the config
Update domain names and URLs
Configure your own Cloudflare tunnel
Set up your own 1Password vault items

Telemetry

Toolbox collects anonymous usage data to help us understand how many people are using this software, so we can prioritize feature updates. We do not collect any personal information, credentials, or the content of your services.

You can view our full privacy policy at contraption.co/privacy, and see the telemetry script at lib/telemetry.rb.

To disable telemetry, set DISABLE_ANONYMOUS_TELEMETRY = true in config.rb or modify the code to remove it.

License

This project is licensed under the MIT License - see the LICENSE file for details.

License

contraptionco/toolbox

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Languages

Error
Looks like something went wrong!