logo

Developing with FirstSpirit in Docker - Secure External Access via ngrok

I recently needed a way to make my FirstSpirit development environment reachable from the internet so that external services—like webhooks or automation tools—could reliably trigger actions during local dev. FirstSpirit doesn’t offer a public endpoint for this by default, so I built a lightweight Docker‑based setup and exposed it over HTTPS using ngrok with a custom domain.

🔧 What it does

  • Runs the official (private) FirstSpirit Docker image in a local container
  • Exposes port 8000 internally to Docker
  • Uses ngrok to tunnel inbound traffic over HTTPS directly to FirstSpirit
  • Enables webhooks, workflows, APIs, or any external integration to hit your local instance securely

🤔 Why I built it

On projects using n8n, automation hooks, or integration testing, I found myself manually poking around localhost and juggling tunnels. But without HTTPS or a stable URL, services like ContentHub, webhooks, OpenAI endpoints, or deployment workflows couldn’t reliably connect to my local FS instance.

This repo solves that with a single custom domain you control, a .env driven login for the secure FirstSpirit registry, and helper scripts for smooth startup and teardown. It gives me

  • Consistent, reproducible dev environments with Docker
  • External webhook addresses that don’t change on restart
  • HTTPS access without manual tunneling setup each time

⚙️ How it works

  1. Clone the repo
  2. Copy .env.example to .env and supply your FirstSpirit Docker credentials
  3. Put your fs-license.conf file under conf/firstspirit/
  4. Copy ngrok.yml.example → ngrok.yml, add your authtoken and custom domain
  5. Copy fs-server.conf.example → fs-server.conf, and replace placeholder domains with your own
  6. Run ./start.sh for the first startup (it logs in and launches the stack)
  7. After startup, your tunnel becomes available at https://your‑domain.ngrok‑free.app

🚀 Developer Flow

cp .env.example .env
# add your credentials

cp conf/ngrok/ngrok.yml.example conf/ngrok/ngrok.yml
# configure token + domain

cp conf/firstspirit/fs-server.conf.example conf/firstspirit/fs-server.conf
# adjust allowedHost settings

mv /path/to/fs-license.conf conf/firstspirit/fs-license.conf

./start.sh             # first run
docker compose up -d   # subsequent runs

When you need to clean up:

docker compose down -v

✅ Why I chose this

  • Trusted FirstSpirit image (pulled from the official private registry)
  • HTTPS tunneling using ngrok with a reserved domain
  • Simple .env‑backed configuration and .example templates
  • Optional health‑checks to monitor readiness
  • Minimal infrastructure—just Docker Compose and a bash script

ℹ️ A few things to note

  • The FirstSpirit image is not open source, licensed separately via Crownpeak. You’ll need your own credentials and license to run it.
  • The ngrok domain must be configured on your account;
  • This setup is meant for development and testing workflows, not production deployment.

Check out the full setup on GitHub → ptylr/docker‑dev‑firstspirit