Installation

Grengin runs on your own infrastructure. There are two ways to install it, and both launch the same browser-based setup wizard on first boot:

• AWS image (recommended): a pre-built machine image that ships with PostgreSQL, Nginx, and SSL tooling already installed.
• Docker: run the installer image on any machine with Docker.

Under the hood, Grengin is a single API binary plus a static web app served by Nginx, backed by PostgreSQL. Nothing sensitive is baked into the install: each instance generates its own secrets on first run.

If you just want the fastest path to a first prompt, start with the Quick Start. This page is the fuller reference.

Requirements

Ports used:

• 80 (HTTP): required. Serves the setup wizard first, then the app.
• 443 (HTTPS): required only if you enable SSL.
• 8080: the internal API port. Nginx proxies to it, so you do not expose it publicly.
• 22 (SSH): for administering a cloud instance.

For a native install, Grengin supports RHEL-based systems (AlmaLinux 9, Rocky Linux 9, RHEL 9, Fedora 39+, CentOS Stream 9) and Debian-based systems (Ubuntu 22.04 and 24.04 LTS, Debian 12, Linux Mint 21+). The Docker path runs on any Linux with Docker 24+ and Docker Compose v2. Node.js and a Rust toolchain are only needed if you build Grengin from source; the AWS image and the Docker installer need neither.

Option 1: AWS image (recommended)

Launch a pre-built Grengin image into your own AWS account from grengin.com/deploy. AWS is the supported cloud today, with more on the way.

When you launch the instance:

• Use at least 2 GB RAM and a 10 GB disk. A t3.small (x86_64) or larger works well.
• In the security group, allow inbound TCP 80 (required), TCP 443 (only if you enable SSL), and TCP 22 for SSH (login user: ubuntu).
• During setup, restrict ports 80 and 22 to your own admin IP. The wizard is unauthenticated until you finish it.

On first boot, the instance auto-starts the installer. Wait about a minute, then open http://<instance-public-ip>/ in your browser and complete the wizard (described below).

Option 2: Docker

To install on any machine with Docker, run the installer image:

docker pull ghcr.io/perter-tech/grengin-image:latest
docker run --rm -p 80:80 ghcr.io/perter-tech/grengin-image:latest

Then open http://localhost and complete the wizard. The installer writes the deployment files (Docker Compose, Nginx, environment) under /opt/grengin, which you can manage afterward with standard docker compose commands.

The setup wizard

Every install method launches the same six-step wizard. Steps 3 to 5 are optional and can be set later.

1. System check. Verifies the operating system, free ports, RAM, and disk.

2. Database. Install a local PostgreSQL (the default) or connect to an existing one by host, port, user, password, and database name.

3. Domain (optional). Enter a domain and optionally enable HTTPS with a free Let’s Encrypt certificate (this needs a contact email and a DNS A record already pointing at the instance). On AWS you can instead claim a free *.grengin.com subdomain offered in the wizard, or skip this to run on the bare IP.

4. Sign-in and SSO (optional). Add Google or Microsoft Entra (Azure AD) OAuth credentials, set allowed email domains, and enable just-in-time user provisioning. If you skip this, Grengin’s hosted SSO proxy is enabled so you can still sign in.

5. AI providers (optional). Paste API keys for OpenAI, Anthropic, Mistral, or Gemini, and tune retrieval (RAG) options. You can add these later from the admin panel.

6. Install. The installer generates unique secrets, writes the configuration, installs the API and web app, configures Nginx, and starts the service. When it finishes, the wizard shows your access URL.

First use

• Your app URL is your domain (over HTTPS if you enabled SSL) or http://<instance-ip>/. The API is served under /api.
• There is no default password. The first account you register through the web UI becomes the initial admin. JWT and encryption secrets are generated uniquely per instance.

Administering a cloud or native instance

SSH in as ubuntu, then use sudo:

# Service status and restart
sudo systemctl status grengin
sudo systemctl restart grengin

# Application logs
sudo journalctl -u grengin -f

# Installer logs
sudo journalctl -u grengin-installer

Key locations:

• Configuration and environment: /etc/grengin/.env
• API binary: /opt/grengin/grengin-api
• Web app files: /var/www/grengin
• Nginx site: /etc/nginx/conf.d/grengin.conf
• Helper scripts: /opt/grengin/scripts

To change the domain, SSL, AI keys, or other settings later, edit /etc/grengin/.env (or use the helper scripts) and run sudo systemctl restart grengin. Docker deployments use the equivalent docker compose commands in /opt/grengin.

Verify the installation

Check that the API responds:

curl http://localhost/api/health

A healthy instance returns an HTTP 200. From another machine, use your domain or instance IP in place of localhost. Then open the app URL in a browser: on first run you will see the setup wizard, and after setup, the sign-in screen.

Security notes

• Finish the wizard promptly. Until you do, port 80 serves an unauthenticated installer, so keep the security group locked to your own IP during setup.
• The AWS image enforces IMDSv2 and disables root and password SSH login.
• Run behind HTTPS in production by enabling SSL in the Domain step.

Next steps

• Start chatting: follow the Quick Start.
• Configure SSO, environment variables, and budgets in Configuration.