Skip to content
Goiabada

Native binaries

Run Goiabada without Docker using pre-built binaries from the releases page.

Download

Section titled “Download”

Download the ZIP for your platform from the releases page. Each ZIP contains both the auth server and admin console binaries:

PlatformZIP fileContains
Linux (x64)goiabada-VERSION-linux-amd64.zipgoiabada-authserver, goiabada-adminconsole
Linux (ARM)goiabada-VERSION-linux-arm64.zipgoiabada-authserver, goiabada-adminconsole
macOS (Intel)goiabada-VERSION-darwin-amd64.zipgoiabada-authserver, goiabada-adminconsole
macOS (Apple Silicon)goiabada-VERSION-darwin-arm64.zipgoiabada-authserver, goiabada-adminconsole
Windowsgoiabada-VERSION-windows-amd64.zipgoiabada-authserver.exe, goiabada-adminconsole.exe
Terminal window
# Example for Linux amd64 - download from the releases page
# https://github.com/leodip/goiabada/releases
unzip goiabada-VERSION-linux-amd64.zip
chmod +x goiabada-authserver goiabada-adminconsole

Prerequisites

Section titled “Prerequisites”
  • A database server (MySQL, PostgreSQL, SQL Server) or SQLite
  • SSL certificates for HTTPS
  • A reverse proxy (Nginx recommended) or direct HTTPS configuration

Configuration

Section titled “Configuration”

Configure via environment variables. You can export them directly or use an environment file.

Auth server configuration

Section titled “Auth server configuration”
Terminal window
# Admin user (created on first startup)
export GOIABADA_ADMIN_EMAIL="[email protected]"
export GOIABADA_ADMIN_PASSWORD="changeme"
export GOIABADA_APPNAME="Goiabada"


# Server URLs
export GOIABADA_AUTHSERVER_BASEURL="https://auth.example.com"
export GOIABADA_AUTHSERVER_INTERNALBASEURL="http://127.0.0.1:9090"


# Listener configuration
export GOIABADA_AUTHSERVER_LISTEN_HOST_HTTP="0.0.0.0"
export GOIABADA_AUTHSERVER_LISTEN_PORT_HTTP="9090"


# Session keys (generate: openssl rand -hex 64 and openssl rand -hex 32)
export GOIABADA_AUTHSERVER_SESSION_AUTHENTICATION_KEY="<64-byte-hex>"
export GOIABADA_AUTHSERVER_SESSION_ENCRYPTION_KEY="<32-byte-hex>"


# Database (MySQL example)
export GOIABADA_DB_TYPE="mysql"
export GOIABADA_DB_USERNAME="goiabada"
export GOIABADA_DB_PASSWORD="your-password"
export GOIABADA_DB_HOST="localhost"
export GOIABADA_DB_PORT="3306"
export GOIABADA_DB_NAME="goiabada"


# Admin console URLs
export GOIABADA_ADMINCONSOLE_BASEURL="https://admin.example.com"


# OAuth client secret for seeding
export GOIABADA_ADMINCONSOLE_OAUTH_CLIENT_SECRET="<generated-secret>"

Admin console configuration

Section titled “Admin console configuration”
Terminal window
# Server URLs
export GOIABADA_ADMINCONSOLE_BASEURL="https://admin.example.com"


# Listener configuration
export GOIABADA_ADMINCONSOLE_LISTEN_HOST_HTTP="0.0.0.0"
export GOIABADA_ADMINCONSOLE_LISTEN_PORT_HTTP="9091"


# OAuth credentials
export GOIABADA_ADMINCONSOLE_OAUTH_CLIENT_ID="admin-console-client"
export GOIABADA_ADMINCONSOLE_OAUTH_CLIENT_SECRET="<same-secret-as-above>"


# Session keys
export GOIABADA_ADMINCONSOLE_SESSION_AUTHENTICATION_KEY="<64-byte-hex>"
export GOIABADA_ADMINCONSOLE_SESSION_ENCRYPTION_KEY="<32-byte-hex>"


# Auth server URLs
export GOIABADA_AUTHSERVER_BASEURL="https://auth.example.com"
export GOIABADA_AUTHSERVER_INTERNALBASEURL="http://127.0.0.1:9090"

Running on Linux with systemd

Section titled “Running on Linux with systemd”

1. Create a dedicated user

Section titled “1. Create a dedicated user”
Terminal window
sudo useradd -r -s /bin/false goiabada
sudo mkdir -p /opt/goiabada
sudo mkdir -p /etc/goiabada
sudo mkdir -p /var/lib/goiabada


sudo mv goiabada-authserver goiabada-adminconsole /opt/goiabada/
sudo chmod +x /opt/goiabada/goiabada-*
sudo chown -R goiabada:goiabada /opt/goiabada
sudo chown -R goiabada:goiabada /var/lib/goiabada

2. Create environment files

Section titled “2. Create environment files”
Terminal window
# Auth server environment
sudo nano /etc/goiabada/authserver.env


# Admin console environment
sudo nano /etc/goiabada/adminconsole.env

3. Create systemd service files

Section titled “3. Create systemd service files”

Auth server (/etc/systemd/system/goiabada-authserver.service):

[Unit]
Description=Goiabada Auth Server
After=network.target mysql.service


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


[Install]
WantedBy=multi-user.target

Admin console (/etc/systemd/system/goiabada-adminconsole.service):

[Unit]
Description=Goiabada Admin Console
After=network.target goiabada-authserver.service
Requires=goiabada-authserver.service


[Service]
Type=simple
User=goiabada
Group=goiabada
WorkingDirectory=/opt/goiabada
EnvironmentFile=/etc/goiabada/adminconsole.env
ExecStart=/opt/goiabada/goiabada-adminconsole
Restart=on-failure
RestartSec=5s


[Install]
WantedBy=multi-user.target

4. Enable and start services

Section titled “4. Enable and start services”
Terminal window
sudo systemctl daemon-reload
sudo systemctl enable goiabada-authserver
sudo systemctl enable goiabada-adminconsole
sudo systemctl start goiabada-authserver
sudo systemctl start goiabada-adminconsole

5. Check status and logs

Section titled “5. Check status and logs”
Terminal window
sudo systemctl status goiabada-authserver
sudo systemctl status goiabada-adminconsole


# View logs
sudo journalctl -u goiabada-authserver -f
sudo journalctl -u goiabada-adminconsole -f

Running on macOS/Windows

Section titled “Running on macOS/Windows”

For production on macOS, consider using launchd:

Terminal window
# Run manually for testing
./goiabada-authserver &
./goiabada-adminconsole &

For persistent services, create launchd plist files in ~/Library/LaunchAgents/.

Reverse proxy

Section titled “Reverse proxy”

For production, use Nginx as a reverse proxy (see reverse proxy guide). Configure Nginx to proxy to:

  • Auth server: http://127.0.0.1:9090
  • Admin console: http://127.0.0.1:9091

Direct HTTPS (optional)

Section titled “Direct HTTPS (optional)”

If you prefer not to use a reverse proxy, configure direct HTTPS:

Terminal window
# Auth server
export GOIABADA_AUTHSERVER_LISTEN_HOST_HTTPS="0.0.0.0"
export GOIABADA_AUTHSERVER_LISTEN_PORT_HTTPS="8443"
export GOIABADA_AUTHSERVER_CERTFILE="/path/to/fullchain.pem"
export GOIABADA_AUTHSERVER_KEYFILE="/path/to/privkey.pem"


# Admin console
export GOIABADA_ADMINCONSOLE_LISTEN_HOST_HTTPS="0.0.0.0"
export GOIABADA_ADMINCONSOLE_LISTEN_PORT_HTTPS="9444"
export GOIABADA_ADMINCONSOLE_CERTFILE="/path/to/fullchain.pem"
export GOIABADA_ADMINCONSOLE_KEYFILE="/path/to/privkey.pem"