Native binaries

This page helps you run Goiabada without Docker: the two binaries from a release, one configuration file, and systemd to keep them running.

You need a Linux server, a database (a MySQL, PostgreSQL or SQL Server you run, or SQLite for a single server), two hostnames under one domain, such as auth.example.com and admin.example.com, and the setup wizard. Both hostnames must share a registrable domain: see What every method needs. A reverse proxy on the same machine, such as Nginx, serves HTTPS in front of them, unless the servers serve HTTPS themselves.

Set it up

Download the release for your platform from the releases page. Each ZIP holds both binaries:

Platform	ZIP
Linux, x86-64	`goiabada-<version>-linux-amd64.zip`
Linux, ARM64	`goiabada-<version>-linux-arm64.zip`
macOS, Intel	`goiabada-<version>-darwin-amd64.zip`
macOS, Apple silicon	`goiabada-<version>-darwin-arm64.zip`
Windows	`goiabada-<version>-windows-amd64.zip`

unzip goiabada-<version>-linux-amd64.zip

Run the setup wizard, and choose Native binaries. Give it the two public URLs, the database, and whether a reverse proxy on this machine forwards to Goiabada (yes by default). Or answer with flags:
Terminal window
```
./goiabada-setup-linux-amd64 --type=native --db=postgres \
  --auth-url=https://auth.example.com --admin-url=https://admin.example.com \
  --db-host=127.0.0.1
```
It writes one file, goiabada.env, which both servers read. It holds every secret, so never commit it, and back up the AES key in it before anything else.

Install the binaries and the file, under a user of their own:

sudo useradd --system --shell /usr/sbin/nologin goiabada
sudo install -d -o goiabada -g goiabada -m 0750 /var/lib/goiabada
sudo install -d -m 0755 /opt/goiabada /etc/goiabada
sudo install -m 0755 goiabada-authserver goiabada-adminconsole /opt/goiabada/
sudo install -o goiabada -g goiabada -m 0600 goiabada.env /etc/goiabada/goiabada.env

Add a systemd unit for each server. /etc/systemd/system/goiabada-authserver.service:

[Unit]
Description=Goiabada auth server
After=network-online.target
Wants=network-online.target

[Service]
User=goiabada
Group=goiabada
WorkingDirectory=/var/lib/goiabada
EnvironmentFile=/etc/goiabada/goiabada.env
ExecStart=/opt/goiabada/goiabada-authserver
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

/etc/systemd/system/goiabada-adminconsole.service is the same, with its own description, ExecStart=/opt/goiabada/goiabada-adminconsole, and After=goiabada-authserver.service added to its [Unit].

Start both:
Terminal window
```
sudo systemctl daemon-reload
sudo systemctl enable --now goiabada-authserver goiabada-adminconsole
until curl -sf http://127.0.0.1:9090/health; do sleep 2; done; echo   # healthy
until curl -sf http://127.0.0.1:9091/health; do sleep 2; done; echo   # healthy
```
The first start migrates and seeds the database before the auth server listens, which takes a few seconds. The admin console listens once the auth server answers it at GOIABADA_AUTHSERVER_INTERNALBASEURL; until then, sudo journalctl -u goiabada-adminconsole shows waiting for the auth server to issue the admin console's token. Without a reverse proxy, check only the auth server here: the admin console reaches it at its public URL, so it listens once you serve HTTPS. sudo journalctl -u goiabada-authserver -f follows the auth server’s log.
Put the reverse proxy in front. Without one, skip this step and serve HTTPS directly instead; your URLs then name ports 9443 and 9444. Proxy auth.example.com to http://127.0.0.1:9090 and admin.example.com to http://127.0.0.1:9091, with the DNS records, Nginx configuration and certificates of Reverse proxy, steps 1 and 3 to 6. Skip its step 2, which starts the Docker Compose files.
Sign in at https://admin.example.com, as First sign-in describes.

To try the binaries before installing them, load the file into a shell and start each one, as the wizard’s last message shows:

set -a && . ./goiabada.env && set +a && ./goiabada-authserver

What the wizard’s answers set

With a reverse proxy on this machine, both servers listen on 127.0.0.1 alone, so nothing past the proxy reaches the plain HTTP they serve, and they trust the forwarded headers of a connection from 127.0.0.1 alone: see Client IP and proxy trust.
With none (--local-proxy=false), both servers listen on every interface and trust no forwarded header. They serve plain HTTP until you serve HTTPS directly.
The rate limiter is on unless you answered no (--rate-limiter=false). See Rate limits.
With SQLite, the database is goiabada.db in the auth server’s working directory, /var/lib/goiabada with the unit above. SQLite suits one auth server: see Database.

The hop to the auth server

The admin console calls the auth server at GOIABADA_AUTHSERVER_INTERNALBASEURL, and listens only once the auth server answers it there.

With a reverse proxy on this machine, the wizard sets it to http://127.0.0.1:9090, the auth server’s own listener. That hop is plain HTTP, but it never leaves the machine, and it works before the proxy, the DNS records and the certificates do. If you change the auth server’s listen host or port, change this URL too.
Without one, it’s the auth server’s public URL, over HTTPS, so the admin console’s client secret and administrators’ tokens are encrypted on the way, and the admin console listens once the auth server serves HTTPS there.

Serve HTTPS without a proxy

Each server serves HTTPS itself once it has a certificate and a key. Set both in goiabada.env, and set each HTTP listen host empty to stop serving plain HTTP:

GOIABADA_AUTHSERVER_CERTFILE="/etc/goiabada/auth.example.com.pem"
GOIABADA_AUTHSERVER_KEYFILE="/etc/goiabada/auth.example.com-key.pem"
GOIABADA_AUTHSERVER_LISTEN_HOST_HTTP=""

GOIABADA_ADMINCONSOLE_CERTFILE="/etc/goiabada/admin.example.com.pem"
GOIABADA_ADMINCONSOLE_KEYFILE="/etc/goiabada/admin.example.com-key.pem"
GOIABADA_ADMINCONSOLE_LISTEN_HOST_HTTP=""

The auth server then listens on port 9443 and the admin console on 9444, on every interface; GOIABADA_AUTHSERVER_LISTEN_PORT_HTTPS and GOIABADA_ADMINCONSOLE_LISTEN_PORT_HTTPS change them. Your public URLs must name those ports, or something must forward 443 to them. The goiabada user must be able to read both keys, and no one else:

sudo chown goiabada:goiabada /etc/goiabada/*-key.pem
sudo chmod 600 /etc/goiabada/*-key.pem

Renewing a certificate takes a restart, since each server reads its files when it starts.

Next steps

Reverse proxyNginx and Let's Encrypt in front of Goiabada.

SecretsWhat goiabada.env protects, and backing up the AES key.

Upgrade GoiabadaInstall a new release, and roll back.