Greptile Docs

Appearance

Manual Setup ​

Fresh

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/ directory from the akupara repository.

Prerequisites ​

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+

Software ​

* Docker 23.x+ (install guide)
* Docker Compose v2.5+ (included with Docker Desktop, or install separately)

From Greptile ​

* Container registry credentials (`CONTAINER_REGISTRY`, `GREPTILE_TAG`)
* Contact [hello@greptile.com](mailto:hello@greptile.com)

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

Setup ​

Clone repository ​

```bash theme={}
git clone https://github.com/greptileai/akupara.git
cd akupara/docker
```

Configure environment ​

```bash theme={}
cp .env.example .env
```

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

Generate secrets ​

```bash theme={}
./bin/generate-secrets.sh
```

Creates `.env.greptile-generated` with `JWT_SECRET`, `TOKEN_ENCRYPTION_KEY`, `LLM_PROXY_KEY`.

Login to registry ​

```bash theme={}
./bin/login-registry.sh
```

Authenticates with Docker Hub or AWS ECR based on `REGISTRY_PROVIDER` in `.env`.

Start Hatchet ​

```bash theme={}
./bin/start-hatchet.sh
```

Wait \~30 seconds for Hatchet to be healthy.

Generate Hatchet token ​

```bash theme={}
./bin/generate-hatchet-token.sh
```

Creates `.env.hatchet-generated` with `HATCHET_CLIENT_TOKEN`.

Start Greptile ​

```bash theme={}
./bin/start-greptile.sh
```

Verify ​

```bash theme={}
docker compose ps
```

All services should show `running` or `healthy`.

Access ​

ServiceURL
Web UIhttp://<IP_ADDRESS>:3000
Hatchet Adminhttp://<IP_ADDRESS>:8080

Configuration ​

Required Settings ​

bash
# 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 ​

Anthropic ​

```bash theme={}
ANTHROPIC_BASE_URL='https://api.anthropic.com'
ANTHROPIC_KEY='sk-ant-...'
```

OpenAI ​

```bash theme={}
OPENAI_API_BASE_URL='https://api.openai.com/v1/'
OPENAI_KEY='sk-...'
```

Azure OpenAI ​

```bash theme={}
AZURE_OPENAI_URL='https://your-resource.openai.azure.com/'
AZURE_OPENAI_KEY='xxx'
AZURE_OPENAI_API_VERSION='2024-07-18'
```

AWS Bedrock ​

```bash theme={}
AWS_ACCESS_KEY_ID='AKIA...'
AWS_SECRET_ACCESS_KEY='xxx'
AWS_REGION='us-east-1'
```

GitHub ​

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'
```

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'
```

External Database (Optional) ​

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

bash
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;

Custom Domain & TLS ​

Point DNS to server IP ​

Create an A record for your domain pointing to the server's public IP.

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
}
```

Update environment ​

```bash theme={}
IP_ADDRESS='greptile.yourcompany.com'
APP_URL='https://greptile.yourcompany.com'
```

Restart services ​

```bash theme={}
docker compose up -d
```

Caddy automatically obtains TLS certificates via Let's Encrypt.

Auto-Start (Systemd) ​

Install systemd services for automatic startup on boot:

bash
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
ServicePurpose
greptile-hatchet.serviceStarts Hatchet stack
greptile-app.serviceStarts Greptile services
greptile-images.timerPeriodic image updates

Operations ​

View logs ​

```bash theme={}
docker compose logs -f                # All services
docker compose logs -f greptile-api   # Specific service
```

Restart a service ​

```bash theme={}
docker compose restart greptile-api
```

Update images ​

```bash theme={}
./bin/login-registry.sh
docker compose pull
docker compose up -d
```

Check Hatchet workflows ​

Access `http://<IP>:8080` to view workflow status, queue depth, and failures.

Troubleshooting ​

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
```

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`

LLM errors ​

```bash theme={}
docker compose logs greptile-llmproxy
```

Verify API keys and endpoint URLs in `.env`.

Hatchet workers not registering ​

Regenerate token and restart:

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

Database connection issues ​

```bash theme={}
docker compose exec greptile-api nc -zv $DB_HOST 5432
```

Resources ​

  • Docker directory
  • .env.example
  • Helper scripts
  • Systemd services

Source

Mirrored from the official Greptile documentation. Self-contained reference copy.