> ## Documentation Index
> Fetch the complete documentation index at: https://www.greptile.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Manual Setup

> Step-by-step guide to deploy Greptile on any Linux server using Docker Compose. Supports AWS, GCP, Azure, on-prem, and air-gapped environments.

Deploy Greptile on any Linux server — AWS, GCP, Azure, on-prem, or air-gapped environments. Uses the [docker/](https://github.com/greptileai/akupara/tree/main/docker) directory from the akupara repository.

## Prerequisites

<AccordionGroup>
  <Accordion title="Server Requirements">
    | Team Size | CPU      | RAM   | Storage |
    | --------- | -------- | ----- | ------- |
    | 5-10 devs | 4 cores  | 16GB  | 100GB   |
    | \~50 devs | 8 cores  | 32GB  | 200GB   |
    | 100 devs  | 32 cores | 128GB | 500GB   |

    **OS:** Ubuntu 20.04+, Amazon Linux 2023, Debian 11+, RHEL 8+
  </Accordion>

  <Accordion title="Software">
    * Docker 23.x+ ([install guide](https://docs.docker.com/engine/install/))
    * Docker Compose v2.5+ (included with Docker Desktop, or [install separately](https://docs.docker.com/compose/install/))
  </Accordion>

  <Accordion title="From Greptile">
    * Container registry credentials (`CONTAINER_REGISTRY`, `GREPTILE_TAG`)
    * Contact [hello@greptile.com](mailto:hello@greptile.com)
  </Accordion>

  <Accordion title="Network">
    **Inbound ports:**

    * `3007` — SCM webhooks (must be publicly accessible)
    * `3000` — Web UI
    * `8080` — Hatchet admin (optional)

    **Outbound access:**

    * LLM provider APIs
    * GitHub/GitLab APIs
    * Container registry
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Clone repository">
    ```bash theme={}
    git clone https://github.com/greptileai/akupara.git
    cd akupara/docker
    ```
  </Step>

  <Step title="Configure environment">
    ```bash theme={}
    cp .env.example .env
    ```

    Edit `.env` with required values (see [Configuration](#configuration) below).
  </Step>

  <Step title="Generate secrets">
    ```bash theme={}
    ./bin/generate-secrets.sh
    ```

    Creates `.env.greptile-generated` with `JWT_SECRET`, `TOKEN_ENCRYPTION_KEY`, `LLM_PROXY_KEY`.
  </Step>

  <Step title="Login to registry">
    ```bash theme={}
    ./bin/login-registry.sh
    ```

    Authenticates with Docker Hub or AWS ECR based on `REGISTRY_PROVIDER` in `.env`.
  </Step>

  <Step title="Start Hatchet">
    ```bash theme={}
    ./bin/start-hatchet.sh
    ```

    Wait \~30 seconds for Hatchet to be healthy.
  </Step>

  <Step title="Generate Hatchet token">
    ```bash theme={}
    ./bin/generate-hatchet-token.sh
    ```

    Creates `.env.hatchet-generated` with `HATCHET_CLIENT_TOKEN`.
  </Step>

  <Step title="Start Greptile">
    ```bash theme={}
    ./bin/start-greptile.sh
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={}
    docker compose ps
    ```

    All services should show `running` or `healthy`.
  </Step>
</Steps>

## Access

| Service       | URL                        |
| ------------- | -------------------------- |
| Web UI        | `http://<IP_ADDRESS>:3000` |
| Hatchet Admin | `http://<IP_ADDRESS>:8080` |

## Configuration

### Required Settings

```bash theme={}
# Container registry (from Greptile)
REGISTRY_PROVIDER='dockerhub'  # or 'ecr'
CONTAINER_REGISTRY='xxx'
GREPTILE_TAG='xxx'

# Server IP (for webhook callbacks)
IP_ADDRESS='your.server.public.ip'
```

### LLM Provider

<AccordionGroup>
  <Accordion title="Anthropic">
    ```bash theme={}
    ANTHROPIC_BASE_URL='https://api.anthropic.com'
    ANTHROPIC_KEY='sk-ant-...'
    ```
  </Accordion>

  <Accordion title="OpenAI">
    ```bash theme={}
    OPENAI_API_BASE_URL='https://api.openai.com/v1/'
    OPENAI_KEY='sk-...'
    ```
  </Accordion>

  <Accordion title="Azure OpenAI">
    ```bash theme={}
    AZURE_OPENAI_URL='https://your-resource.openai.azure.com/'
    AZURE_OPENAI_KEY='xxx'
    AZURE_OPENAI_API_VERSION='2024-07-18'
    ```
  </Accordion>

  <Accordion title="AWS Bedrock">
    ```bash theme={}
    AWS_ACCESS_KEY_ID='AKIA...'
    AWS_SECRET_ACCESS_KEY='xxx'
    AWS_REGION='us-east-1'
    ```
  </Accordion>
</AccordionGroup>

### GitHub

<AccordionGroup>
  <Accordion title="GitHub Cloud">
    ```bash theme={}
    GITHUB_ENABLED='true'
    GITHUB_ENTERPRISE_ENABLED='false'
    GITHUB_APP_ID='123456'
    GITHUB_CLIENT_ID='Iv1.xxx'
    GITHUB_CLIENT_SECRET='xxx'
    GITHUB_PRIVATE_KEY='-----BEGIN RSA PRIVATE KEY-----...'
    WEBHOOK_SECRET='xxx'
    ```
  </Accordion>

  <Accordion title="GitHub Enterprise">
    ```bash theme={}
    GITHUB_ENABLED='false'
    GITHUB_ENTERPRISE_ENABLED='true'
    GITHUB_ENTERPRISE_URL='https://github.yourcompany.com'
    GITHUB_ENTERPRISE_API_URL='https://github.yourcompany.com/api/v3/'
    GITHUB_APP_ID='123456'
    GITHUB_CLIENT_ID='Iv1.xxx'
    GITHUB_CLIENT_SECRET='xxx'
    GITHUB_PRIVATE_KEY='-----BEGIN RSA PRIVATE KEY-----...'
    WEBHOOK_SECRET='xxx'
    ```
  </Accordion>
</AccordionGroup>

### External Database (Optional)

To use managed PostgreSQL (RDS, Cloud SQL) instead of the bundled container:

```bash theme={}
DB_HOST='your-database-endpoint'
DB_PORT='5432'
DB_USER='greptile'
DB_PASSWORD='xxx'
DB_NAME='greptile'
DB_SSL_DISABLE='false'
```

<Note>
  PostgreSQL 15+ with pgvector extension required. Run `CREATE EXTENSION IF NOT EXISTS vector;`
</Note>

## Custom Domain & TLS

<Steps>
  <Step title="Point DNS to server IP">
    Create an A record for your domain pointing to the server's public IP.
  </Step>

  <Step title="Configure Caddy">
    ```bash theme={}
    cp Caddyfile.example Caddyfile
    ```

    Edit `Caddyfile`:

    ```
    greptile.yourcompany.com {
        reverse_proxy greptile-web:3000
    }

    greptile.yourcompany.com:3007 {
        reverse_proxy greptile-webhook:3007
    }
    ```
  </Step>

  <Step title="Update environment">
    ```bash theme={}
    IP_ADDRESS='greptile.yourcompany.com'
    APP_URL='https://greptile.yourcompany.com'
    ```
  </Step>

  <Step title="Restart services">
    ```bash theme={}
    docker compose up -d
    ```

    Caddy automatically obtains TLS certificates via Let's Encrypt.
  </Step>
</Steps>

## Auto-Start (Systemd)

Install [systemd services](https://github.com/greptileai/akupara/tree/main/docker/systemd) for automatic startup on boot:

```bash theme={}
sudo cp systemd/*.service /etc/systemd/system/
sudo cp systemd/*.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable greptile-hatchet greptile-app
sudo systemctl start greptile-hatchet greptile-app
```

| Service                    | Purpose                  |
| -------------------------- | ------------------------ |
| `greptile-hatchet.service` | Starts Hatchet stack     |
| `greptile-app.service`     | Starts Greptile services |
| `greptile-images.timer`    | Periodic image updates   |

## Operations

<AccordionGroup>
  <Accordion title="View logs">
    ```bash theme={}
    docker compose logs -f                # All services
    docker compose logs -f greptile-api   # Specific service
    ```
  </Accordion>

  <Accordion title="Restart a service">
    ```bash theme={}
    docker compose restart greptile-api
    ```
  </Accordion>

  <Accordion title="Update images">
    ```bash theme={}
    ./bin/login-registry.sh
    docker compose pull
    docker compose up -d
    ```
  </Accordion>

  <Accordion title="Check Hatchet workflows">
    Access `http://<IP>:8080` to view workflow status, queue depth, and failures.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Services won't start">
    ```bash theme={}
    docker compose config          # Validate compose file
    docker compose logs <service>  # Check specific service logs
    sudo systemctl status docker   # Check Docker daemon
    ```
  </Accordion>

  <Accordion title="Webhooks not receiving">
    1. Verify `IP_ADDRESS` is publicly accessible
    2. Check firewall allows inbound on port 3007
    3. Confirm GitHub App webhook URL: `http://<IP>:3007/webhook`
  </Accordion>

  <Accordion title="LLM errors">
    ```bash theme={}
    docker compose logs greptile-llmproxy
    ```

    Verify API keys and endpoint URLs in `.env`.
  </Accordion>

  <Accordion title="Hatchet workers not registering">
    Regenerate token and restart:

    ```bash theme={}
    ./bin/generate-hatchet-token.sh
    docker compose restart
    ```
  </Accordion>

  <Accordion title="Database connection issues">
    ```bash theme={}
    docker compose exec greptile-api nc -zv $DB_HOST 5432
    ```
  </Accordion>
</AccordionGroup>

## Resources

* [Docker directory](https://github.com/greptileai/akupara/tree/main/docker)
* [.env.example](https://github.com/greptileai/akupara/blob/main/docker/.env.example)
* [Helper scripts](https://github.com/greptileai/akupara/tree/main/docker/bin)
* [Systemd services](https://github.com/greptileai/akupara/tree/main/docker/systemd)