Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ogis.dev/llms.txt

Use this file to discover all available pages before exploring further.

Run your own ogis instance for full control over your image generation.

​
One-Click Deploy

Deploy on Railway

One-click deploy to Railway

Deploy to Google Cloud

Deploy to Google Cloud Run

​
Docker

The recommended way to run ogis: 
docker run -d -p 3000:3000 twango/ogis:latest
With environment variables: 
docker run -d \
  -p 3000:3000 \
  -e OGIS_DEFAULT_TEMPLATE=minimal \
  -e OGIS_HMAC_SECRET=your-secret-key \
  twango/ogis:latest

​
Docker Compose

For development or simple deployments: 
# docker-compose.yml
services:
  ogis:
    image: twango/ogis:latest
    ports:
      - "3000:3000"
    environment:
      - OGIS_DEFAULT_TEMPLATE=twilight
      - OGIS_CACHE_SIZE=1000
    restart: unless-stopped

docker compose up -d

​
Building from Source

Requirements: Rust 1.70+ 
git clone https://github.com/twangodev/ogis.git
cd ogis
cargo build --release
./target/release/ogis

​
Configuration

Configure ogis via environment variables (prefixed with OGIS_) or CLI arguments.

​
Server Options

Environment VariableCLI ArgumentDefaultDescription
OGIS_PORT--port3000Server port
OGIS_HOST--host0.0.0.0Server bind address

​
Image Generation

Environment VariableCLI ArgumentDefaultDescription
OGIS_DEFAULT_TEMPLATE--default-templatetwilightDefault template when not specified
OGIS_DEFAULT_TITLE--default-titleogisDefault title text
OGIS_DEFAULT_DESCRIPTION--default-description-Default description text
OGIS_MAX_INPUT_LENGTH--max-input-length500Maximum text length

​
Caching

Environment VariableCLI ArgumentDefaultDescription
OGIS_CACHE_SIZE--cache-size1000Number of images to cache in memory

​
Security

Environment VariableCLI ArgumentDefaultDescription
OGIS_HMAC_SECRET--hmac-secret-Enable HMAC authentication (see Authentication)

​
Image Fetching

Environment VariableCLI ArgumentDefaultDescription
OGIS_IMAGE_TIMEOUT--image-timeout10Timeout for fetching external images (seconds)
OGIS_IMAGE_MAX_SIZE--image-max-size5242880Maximum image size (bytes, default 5MB)
OGIS_IMAGE_HTTPS_ONLY--image-https-onlytrueOnly allow HTTPS URLs for images
Run ogis --help for the complete list of options.

​
Health Checks

ogis exposes a health endpoint for container orchestration: 
curl http://localhost:3000/health
Returns 200 OK when the service is ready.

​
Reverse Proxy

server {
    listen 80;
    server_name ogis.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache_valid 200 1h;
    }
}

​
Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ogis
spec:
  replicas: 2
  selector:
    matchLabels:
      app: ogis
  template:
    metadata:
      labels:
        app: ogis
    spec:
      containers:
      - name: ogis
        image: twango/ogis:latest
        ports:
        - containerPort: 3000
        env:
        - name: OGIS_CACHE_SIZE
          value: "2000"
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
        readinessProbe:
          httpGet:
            path: /health
            port: 3000
---
apiVersion: v1
kind: Service
metadata:
  name: ogis
spec:
  selector:
    app: ogis
  ports:
  - port: 80
    targetPort: 3000

​
Using Your Instance

Point the SDK to your self-hosted instance: 
import { OgisClient } from 'ogis';

const ogis = new OgisClient({
  baseUrl: 'https://ogis.example.com'
});
For private instances, see Authentication.