How to Self-Host IT-Tools with Docker Compose and Caddy: 80+ Offline Developer & Sysadmin Utilities with HTTP Basic Auth

In the daily workflow of software engineers, DevOps specialists, and system administrators, small utility tasks occur dozens of times every day. Whether formatting an unreadable minified JSON payload, inspecting the claims and expiration timestamps of a JSON Web Token (JWT), converting epoch timestamps to human-readable dates, testing complex regular expressions, calculating IPv4 CIDR subnets, or converting raw docker run commands into declarative Docker Compose YAML files, developers constantly seek rapid, frictionless tools to get their jobs done.

However, the prevailing habit of searching Google for “JSON formatter online”, “JWT decoder”, or “base64 encoder” introduces catastrophic operational security and compliance vulnerabilities. When engineers paste customer records, production JWT bearer tokens containing Personally Identifiable Information (PII), proprietary SQL queries, and internal API keys into third-party, ad-supported converter websites, that sensitive data is frequently logged by web servers, cached by third-party analytics scripts, or leaked into corporate proxy logs. For organizations subject to SOC 2, ISO 27001, HIPAA, or GDPR, this unvetted data exfiltration represents a severe compliance violation.

IT-Tools is an outstanding, open-source collection of over 80 essential developer and system administrator utilities bundled into a responsive, unified web application. Because IT-Tools executes all data transformations entirely client-side inside the user’s browser, no input data ever leaves the local machine. By self-hosting IT-Tools inside a lightweight Docker container behind a secured reverse proxy like Caddy with HTTP Basic Authentication, your organization or homelab gains a fast, private, air-gapped utility suite that prevents sensitive data leaks entirely.

Architecture & Data Privacy Flow

The beauty of IT-Tools lies in its static, client-side execution model. The containerized application is delivered as an optimized Nginx web server hosting pre-compiled Vue.js and TypeScript single-page application (SPA) assets. The following diagram illustrates how user interactions, authentication, and offline cryptographic operations operate within your secured boundary:

+-----------------------------------------------------------------------+
|             Developer Workstation / Corporate LAN / VPN               |
|            (Chrome, Firefox, Safari, Brave Web Browsers)              |
+-----------------------------------------------------------------------+
                                   |
                                   | HTTPS (Port 443 / TLS 1.3)
                                   | + HTTP Basic Auth (Authorization Header)
                                   v
+-----------------------------------------------------------------------+
|                    Edge Reverse Proxy: Caddy v2                       |
|   - Automatic Let's Encrypt / ZeroSSL TLS Certificate Management     |
|   - Basic Authentication Gatekeeper (bcrypt / Argon2 password hash)   |
|   - Strict Security Headers (HSTS, CSP, X-Frame-Options)              |
+-----------------------------------------------------------------------+
                                   |
                                   | HTTP (Internal Isolated Network: it_tools_net)
                                   v
+-----------------------------------------------------------------------+
|                       IT-Tools Container (Core)                       |
|   - Image: corentinth/it-tools:latest                                 |
|   - Ultra-lightweight static web server (Nginx Alpine)                |
|   - Serves Vue.js SPA assets (HTML/JS/CSS/WebAssembly)                |
+-----------------------------------------------------------------------+
                                   |
                                   | SPA Assets Downloaded to Browser
                                   v
+-----------------------------------------------------------------------+
|                   Client-Side Browser Execution Sandbox               |
|   - 100% of JSON parsing, regex, JWT decoding, and hashing occurs     |
|     locally within the browser's JavaScript V8/WebAssembly engine.    |
|   - ZERO network requests sent back to the server for processing!     |
+-----------------------------------------------------------------------+

Key security architectural advantages of this setup:

• Zero Data Exfiltration: Because IT-Tools performs conversions, hashing, and formatting in browser memory using JavaScript, sensitive secrets, database schemas, and private keys never touch server disk storage or remote networks.
• Edge Access Control: Because the upstream IT-Tools container does not have native multi-user authentication, Caddy serves as an authenticated perimeter gate, enforcing HTTP Basic Authentication before any static assets can be loaded.
• Sub-Millisecond Execution: Once the single-page application is cached by the client browser, tools operate instantaneously without API latency or server CPU overhead.

Prerequisites & Environment Preparation

To deploy this stack, verify that your environment satisfies the following baseline requirements:

• Operating System: Any Linux distribution with Docker Engine 24+ (Ubuntu 22.04/24.04, Debian 12, Rocky Linux, or Alpine).
• Resource Requirements: Minimal footprint. IT-Tools consumes less than 30 MB of RAM and negligible CPU cycles. Even a $4/month VPS or Raspberry Pi 4/5 can easily host this service alongside other workloads.
• Domain / DNS: A public or internal DNS A/AAAA record (such as tools.yourdomain.com) pointing to your host server’s IP address.
• Software: Docker Engine and Docker Compose v2 installed.

Create a dedicated directory on your server to house your configuration files:

sudo mkdir -p /opt/it-tools/{caddy_data,caddy_config}
cd /opt/it-tools

Step 1: Generate Secure Password Hashes for Caddy

Caddy’s basicauth directive requires passwords to be hashed using bcrypt or Argon2. Never store plaintext credentials in your configuration. You can generate a bcrypt hash directly using Caddy’s built-in CLI tool inside a temporary container:

# Replace 'YourSuperSecretPassword123!' with your desired strong password
docker run --rm caddy:2-alpine caddy hash-password --plaintext 'YourSuperSecretPassword123!'

The command will output a bcrypt hash string formatted like:

$2a$14$Z1qG7Gv3uO6xR9.2W5P1u.N1eW7yZ6z5s8T9U4v3w2x1y0zABCDEF

Copy this hash for use in the next step.

Step 2: Configure Caddy Reverse Proxy (Caddyfile)

Create the /opt/it-tools/Caddyfile. This configuration specifies your domain, terminates automatic Let’s Encrypt TLS, injects HTTP security headers, enforces HTTP Basic Authentication, and reverse proxies requests to the internal IT-Tools container:

{$TOOLS_DOMAIN:tools.yourdomain.com} {
    encode zstd gzip

    # Enforce HTTP Basic Authentication for authorized team members
    basicauth * {
        # Username: devops (replace with your username and generated hash)
        devops $2a$14$Z1qG7Gv3uO6xR9.2W5P1u.N1eW7yZ6z5s8T9U4v3w2x1y0zABCDEF
    }

    # Security Hardening Headers
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Content-Type-Options "nosniff"
        X-Frame-Options "DENY"
        Referrer-Policy "strict-origin-when-cross-origin"
        Permissions-Policy "camera=(), microphone=(), geolocation=()"
        Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self' blob:; worker-src 'self' blob:;"
    }

    # Reverse proxy to the internal IT-Tools Nginx container
    reverse_proxy it-tools-app:80 {
        header_up Host {host}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto https
    }
}

Security Note: The Content Security Policy (CSP) restricts external script loading, ensuring that no malicious third-party trackers or injected payloads can intercept sensitive data pasted into the developer tools.

Step 3: Define Environment Variables (.env)

Create a simple .env file to centralize your public domain name and container settings:

cat << 'EOF' > /opt/it-tools/.env
# Public FQDN for your IT-Tools instance
TOOLS_DOMAIN=tools.yourdomain.com
EOF
chmod 600 /opt/it-tools/.env

Step 4: Create Production Docker Compose Configuration

Create the /opt/it-tools/docker-compose.yml file. We pin images to stable release tags, disable privileged capabilities, and isolate the internal application behind a private bridge network:

services:
  # ----------------------------------------------------------------------------
  # IT-Tools Core Application (Static Vue.js / Nginx)
  # ----------------------------------------------------------------------------
  it-tools-app:
    image: corentinth/it-tools:latest
    container_name: it-tools-app
    restart: unless-stopped
    read_only: true
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp:rw,noexec,nosuid,size=16m
      - /var/cache/nginx:rw,noexec,nosuid,size=32m
      - /var/run:rw,noexec,nosuid,size=16m
    networks:
      - it_tools_internal
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:80/"]
      interval: 15s
      timeout: 5s
      retries: 3

  # ----------------------------------------------------------------------------
  # Caddy Reverse Proxy (Edge TLS & Basic Authentication)
  # ----------------------------------------------------------------------------
  caddy:
    image: caddy:2-alpine
    container_name: it-tools-caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp" # HTTP/3 QUIC support
    volumes:
      - /opt/it-tools/Caddyfile:/etc/caddy/Caddyfile:ro
      - /opt/it-tools/caddy_data:/data
      - /opt/it-tools/caddy_config:/config
    env_file:
      - /opt/it-tools/.env
    networks:
      - it_tools_internal
      - it_tools_public

networks:
  it_tools_internal:
    internal: true
  it_tools_public:
    internal: false

Notice the hardened container security configurations:

• read_only: true: The container filesystem is mounted strictly read-only, preventing any unauthorized modifications or file injections.
• tmpfs: Ephemeral in-memory tmpfs mounts allow Nginx to store PID and cache files without writing to host disk.
• internal: true: The it_tools_internal network has no direct access to the public internet, completely air-gapping the application container.

Step 5: Launch and Validate the Stack

Start the services using Docker Compose:

cd /opt/it-tools
docker compose up -d

Check the container health status and review Caddy logs for SSL certificate provisioning:

docker compose ps
docker compose logs -f caddy

Open your browser and navigate to https://tools.yourdomain.com. Your browser will prompt you for HTTP Basic Authentication credentials. Enter the username (devops) and password you configured in Step 1. Upon authentication, the comprehensive IT-Tools interface loads instantly.

Essential Tools Inside IT-Tools

IT-Tools organizes its utilities into clean categories accessible via quick search (Ctrl + K or Cmd + K):

• Converters:
  • JSON <> YAML <> XML <> CSV: Seamlessly convert data serialization formats without uploading schemas to third-party endpoints.
  • Docker Run to Compose: Paste complex docker run -d -p 8080:80 ... commands and automatically obtain clean, indentation-perfect compose.yaml snippets.
  • Base64, Hex <> ASCII: Binary and text encoding transformations with real-time feedback.
• Security & Cryptography:
  • JWT Parser & Inspector: Decode JWT headers and payloads, inspect token signature algorithms, and calculate remaining token lifetimes without exposing credentials.
  • Bcrypt & Argon2 Generator: Generate and verify salted password hashes for application backends.
  • Hash Calculator: Calculate SHA-256, SHA-512, MD5, and HMAC digests completely offline.
  • X.509 Certificate Decoder: Inspect public SSL/TLS certificates, SAN extensions, and expiration dates.
• DevOps & Infrastructure:
  • Crontab Generator: Interactive visual schedule builder for Unix cron syntax.
  • IPv4 / IPv6 Subnet Calculator: Calculate network masks, broadcast addresses, usable host ranges, and CIDR blocks.
  • CHMOD Calculator: Interactive permission bit visualizer (numeric octal and symbolic modes).
  • SQL Formatter: Reformat messy queries into structured, readable SQL statements.

Troubleshooting Common Operational Issues

1. HTTP 401 Unauthorized / Password Hash Mismatch

Symptom: Entering the correct username and password repeatedly triggers a 401 Authorization Required prompt in the browser.

Root Cause: Caddy evaluates the bcrypt hash strictly. If special characters like $ were interpreted as environment variables by shell interpolation or Docker Compose, the hash in the Caddyfile became corrupted.

Resolution: In your Caddyfile, ensure the bcrypt string is entered verbatim without escaping, or regenerate the hash using single quotes. Test your hash manually using the Caddy container:

# Reload Caddy to test changes without dropping connections
docker compose exec it-tools-caddy caddy reload --config /etc/caddy/Caddyfile

2. Content-Security-Policy Violations / Blocked Assets

Symptom: Certain tools (such as WebAssembly-based hash calculations or QR code downloads) fail to generate, and browser developer console reports Refused to compile or execute script because it violates Content Security Policy.

Root Cause: Overly restrictive CSP directives blocking WebAssembly (Wasm) evaluation or blob URL creation.

Resolution: Ensure your Content-Security-Policy header in the Caddyfile includes 'unsafe-eval' in script-src and permits blob: in worker-src and connect-src.

3. Let’s Encrypt Rate Limits on Domain Re-deployments

Symptom: Caddy logs display HTTP 429 Too Many Requests: Error creating new cert - acme: rate limited.

Root Cause: Repeatedly creating and destroying the Caddy container without mounting the persistent caddy_data volume causes Let’s Encrypt to exhaust weekly certificate limits.

Resolution: Always verify that /opt/it-tools/caddy_data:/data is mounted in your docker-compose.yml so certificates are persisted across container restarts.

Conclusion & Key Takeaways

By self-hosting IT-Tools with Docker Compose and Caddy, your organization eliminates the pervasive risk of accidental credential leakage to public online converter websites. You provide your engineering team with a blazing-fast, 100% offline, zero-telemetry utility toolbox that operates cleanly behind encrypted, authenticated edge security.

For additional layers of defense, you can integrate this service with Cloudflare Tunnels with Zero Trust email/SAML validation, or enforce Single Sign-On across your team by pairing Caddy with an identity provider like Authentik.