Use your own server: the host app

What the host app does

The host app is a small web server you run on your own machine. Once it's connected to your account it:

• serves every site folder you put in its sites/ folder
• serves sites you upload in the dashboard, and switches versions when you roll back
• adds your widget to every page, unless you turn that off
• gets free HTTPS certificates for your domains (with the Docker setup)
• shows up in Dashboard → Website, with whether it's online

You don't need it if we host your site for you. It's for people who want the files on a machine they control.

What you need

• A Linux server running Ubuntu or Debian, with a login that can use sudo. A small cloud server works well.
• Ports 80 and 443 open to the internet, for websites and HTTPS.
• Your domain, if you have one. You can also start without it.

Install

1. Get a pairing code. In your dashboard, go to Website, then Use my own server, then Add a server. You get a code like ABCD-1234. Codes work for 24 hours.

2. Run the installer on your server, with your code in it:

   ShellCopy

   curl -fsSL https://justagoodguy.us/downloads/host/install.sh | sudo bash -s -- --code ABCD-1234

   It installs Docker if needed, starts the host app behind Caddy for automatic HTTPS, and connects it to your account. At the end it prints the link to your setup page. Keep that link private.

3. Point your domain at the server. At your registrar, add an A record for @ and for www, each with your server's IP address.

4. Visit your domain. The first visit can take a few seconds while the HTTPS certificate is set up.

Everything lives in /opt/goodguy: your site folders in /opt/goodguy/sites, and the settings in /opt/goodguy/.env.

Installer options

Add these after bash -s --:

Without the installer

If you'd rather set it up by hand, the host app ships with a Dockerfile, a docker-compose.yml and a Caddyfile. Put them in one folder with the built dist/host.mjs, add a .env file with your settings (see Settings), and start it:

docker compose up -d --build

Connect it to your account

If you didn't pass --code to the installer, open the setup page link it printed. It looks like http://YOUR-SERVER-IP/_gg/setup?token=.... There you can connect in two ways:

• With a pairing code (easiest). Type the code from Website → Use my own server → Add a server.
• By signing in. Enter your Just a Good Guy email and password. Your password is used once, to get a connection key for this server, and is never saved on the server. Only a business owner can connect a server.

The setup page also shows which business the server is connected to, which sites it serves and where each one comes from, when it last synced, and a button to disconnect it.

Once it's connected, your dashboard shows the server as online. It checks in about once a minute, and counts as online if it was seen in the last 2 minutes.

Lost the setup link?

The setup page needs its setup token, so nobody else can connect your server to their own account. The installer creates the token for you. To see it:

sudo grep SETUP_TOKEN /opt/goodguy/.env

Then open http://YOUR-SERVER-IP/_gg/setup?token= with the token on the end. Pages opened from the server itself don't need the token.

Add your sites

There are two ways, and you can mix them.

Upload it in the dashboard. Go to Website and upload a zip of your site. The server shows the new version within seconds. For uploaded sites, turn the widget on or off in the dashboard.

Put a folder on the server. Copy your site's folder into /opt/goodguy/sites/, for example with an SFTP app. Each folder needs an index.html at the top.

sites/
  joesplumbing.com/
    index.html
    about.html
    images/
  spring-offer/
    index.html

• Name a folder after your domain (sites/joesplumbing.com) and it becomes the site for that domain. www.joesplumbing.com is included.
• Any other name (sites/spring-offer) becomes a site on a free address, if that name isn't already taken.
• New folders are picked up within a few seconds, and appear in your dashboard after the next check-in.
• If the server has only one site, it shows that site for every address, including the server's bare IP address.
• Your sites keep working if the connection to Just a Good Guy drops. The server keeps the last version it received.

Turning the widget off for one site

The host app adds your widget to each page. To leave it out for one site, add a file called .goodguy.json to that site's folder:

{ "injectWidget": false }

Settings

With the installer, change settings in /opt/goodguy/.env (it holds JAGG_API, SETUP_TOKEN and SITES_DOMAIN), then restart: cd /opt/goodguy && sudo docker compose up -d. Running the host app yourself, set these as environment variables or command-line options.

Other commands:

node host.mjs status       # what it's connected to, and its sites
node host.mjs setup-url    # the setup page link, with its token
node host.mjs disconnect   # forget the connection on this server
node host.mjs --help

With the Docker install, run them inside the container, for example cd /opt/goodguy && sudo docker compose exec host node /app/host.mjs status. Logs: sudo docker compose logs -f host (Docker) or journalctl -u goodguy-host -f (without Docker).

For developers

HTTPS with Caddy: the ask endpoint

Caddy's on-demand TLS asks the host app before it requests a certificate, so nobody can make your server request certificates for random names. The host app answers at:

GET /_gg/tls-ok?domain=joesplumbing.com

It returns 200 for a host name it serves and 404 for anything else. The Caddyfile that ships with the host app uses it like this:

{
  on_demand_tls {
    ask http://host:8200/_gg/tls-ok
  }
}

https:// {
  tls {
    on_demand
  }
  reverse_proxy host:8200
}

It also keeps plain HTTP working for bare IP addresses, so the setup page opens before your DNS is ready, and redirects named hosts to HTTPS.

GET /_gg/health returns { ok, version, paired, sites, uptime } for monitoring.

How it talks to your account

The host app only makes outgoing requests, so it works behind a home router or firewall as long as it can reach the internet. All requests go to JAGG_API and carry the server's connection key as Authorization: Bearer hst_....

Each site in the sync answer has its host names, its folder name, the version to serve and where to download it, whether to add the widget, and the exact widget <script> tag to add.

If the dashboard removes the server, its key stops working and the host app asks you to connect it again.