Quick Start & Setup
Relevant source files
The following files were used as context for generating this wiki page:
Hoop is a layer 7 gateway designed to sit between users (engineers, AI agents, service accounts) and infrastructure such as databases, Kubernetes clusters, and servers. The "Quick Start & Setup" process facilitates the deployment of the gateway, the configuration of authentication, and the connection of target resources via agents.
Sources: README.md:1-25, gateway/README.md:1-10
Gateway Deployment Methods
The Hoop gateway can be deployed using several methods depending on the environment, ranging from local Docker Compose setups for evaluation to production-ready Helm charts for Kubernetes.
Docker Compose (Recommended for Quick Start)
The fastest way to get a Hoop instance running is using Docker Compose. This method automatically handles the creation of a JWT_SECRET_KEY and starts the necessary containers.
# create a jwt secret for auth
echo "JWT_SECRET_KEY=$(openssl rand -hex 32)" >> .env
# download and run
curl -sL https://hoop.dev/docker-compose.yml > docker-compose.yml && \
docker compose up
Sources: README.md:95-103, scripts/install.sh:131-158
Kubernetes via Helm
For production environments, Hoop provides Helm charts for both the Gateway and the Agent. The Gateway requires a PostgreSQL URI and Identity Provider (IDP) configurations.
| Configuration Variable | Description |
|---|---|
POSTGRES_DB_URI | Connection string for the PostgreSQL database. |
API_URL | The public URL where the gateway will be accessible. |
IDP_ISSUER | The URL of the OIDC/SAML identity provider. |
Sources: deploy/helm-chart/README.md:14-25, gateway/README.md:25-30
Setup Flow Architecture
The following diagram illustrates the high-level flow of setting up a new Hoop instance, from initial container launch to user onboarding.
The setup process involves verifying system requirements, generating security credentials, and initializing the web portal for the first administrative user.
Sources: scripts/install.sh:75-120, scripts/install.sh:180-210
Component Development Setup
Gateway (Golang)
Developers working on the gateway backend need Golang 1.23+ and a PostgreSQL instance. The gateway runs on port 8009 by default.
- Navigate to
cmd/gateway. - Configure
.envfrom.env.example. - Execute
go run main.go.
Sources: gateway/README.md:12-40
Modern WebApp (React/Vite)
The modern UI (webapp_v2) uses Vite and Mantine. It proxies API requests to the gateway and asset requests to the legacy ClojureScript server.
- Install:
npm install - Run Full Stack:
npm run dev:full(Runs Vite and shadow-cljs) - Default Port:
http://localhost:5173
Sources: webapp_v2/README.md:10-45
Agent Deployment
Once the gateway is running, agents must be deployed within the target infrastructure to proxy connections. Agents require a HOOP_KEY generated by the gateway.
Deployment Options
Agents can be deployed as standalone containers, Kubernetes sidecars, or via the Hoop CLI.
Sources: webapp_v2/src/pages/Agents/Create/DeploymentInstructions.jsx:20-130, deploy/helm-chart/README.md:33-40
Authentication & Identity
Hoop supports two primary authentication methods:
- Local Auth: Email and password stored in the local database.
- OAuth/IDP: Integration with providers like Okta, Google, or Azure AD via OIDC.
The jwt-token is stored in localStorage and shared between the React shell and the legacy ClojureScript components to maintain session state.
Sources: webapp_v2/README.md:70-85, README.md:147-152
Quick Start & Setup provides the foundation for establishing a secure layer 7 gateway. By following the automated scripts or manual container deployments, administrators can quickly move from an empty environment to a governed infrastructure access point with active data masking and audit capabilities.