Install behind Cloudflare Tunnel

Any Linux machine (a computer at home, an old PC, a VPS) can serve SkillPouch through Cloudflare Tunnel: no open router ports, HTTPS by Cloudflare, and every push to main deploys itself with zero downtime and automatic rollback.

The examples use app.skillpouch.net; use your own hostname.

1. Give the server read access to the repository

On the server:

ssh-keygen -t ed25519 -N '' -f ~/.ssh/id_ed25519 -C skillpouch-server
cat ~/.ssh/id_ed25519.pub

On GitHub, open your copy of the repository → Settings → Deploy keys → Add deploy key, paste the key and leave write access off.

2. Clone and run the setup

git clone git@github.com:skillpouch/skillpouch.git ~/skillpouch
~/skillpouch/deploy/tunnel/setup.sh

The setup:

installs Docker, cloudflared and automatic security updates
creates the data folders in /srv/skillpouch
generates the secrets and database passwords
starts Postgres and Caddy
prepares automatic deploys and runs the first deploy

The first run takes 10–20 minutes. Running it again is safe: it keeps your secrets and env files.

3. Configure the app

Edit ~/skillpouch/deploy/env/api.env:

ADMIN_EMAILS: your email, for the admin dashboard
API_PUBLIC_URL and WEB_ORIGIN: your hostname
the GitHub and/or Google sign-in apps (Sign-in and GitHub)
billing, only if you want paid plans (Billing)

Set PUBLIC_HOST in deploy/env/stack.env to the same hostname. Apply the changes:

~/skillpouch/deploy/tunnel/update.sh --force

All settings are described in Configuration.

4. Connect the tunnel

In the Cloudflare dashboard open Zero Trust → Networks → Tunnels → Create a tunnel → Cloudflared and give it a name.
Copy the sudo cloudflared service install <token> command it shows and run it on the server.
Add a Public hostname: your hostname → service HTTP → localhost:80.

Open your hostname in a browser. SkillPouch is running.

5. Deploy from GitHub Actions

After CI passes on main, the deploy workflow runs on the server through a self-hosted runner. Install the runner once, as the same user that ran setup.sh:

On GitHub, open the repository → Settings → Actions → Runners → New self-hosted runner → Linux and your architecture.

setup.sh already downloaded the runner to ~/actions-runner. Copy only the token from GitHub’s page, then:

cd ~/actions-runner
./config.sh --url https://github.com/<owner>/skillpouch --token <TOKEN> \
  --name "$(hostname)" --labels skillpouch-server --unattended
sudo ./svc.sh install && sudo ./svc.sh start

Set the repository variable SKILLPOUCH_DIR (Settings → Secrets and variables → Actions → Variables) to the checkout’s path, for example /home/deploy/skillpouch.

The runner updates itself. If the server is offline for more than 14 days, GitHub removes it; run config.sh again with a new token.