GrapheneOS-AttestationServer-Docker/README.md

# GrapheneOS AttestationServer Docker

Dockerized deployment of [GrapheneOS AttestationServer](https://github.com/GrapheneOS/AttestationServer) for local attestation.

## Overview

This project provides a containerized setup for running your own GrapheneOS AttestationServer. It includes:

- **AttestationServer** - The main Java application handling attestations
- **Caddy** - Reverse proxy with HTTPS support
- **SQLite** - Local database storage for attestation data

## Prerequisites

Before running the server, ensure you have:

1. **Docker** and **Docker Compose** installed
2. **TLS certificates** for your domain in the `certs/` directory
3. **DNS or hosts file configuration** to resolve your domain to your server

## Configuration

### 1. Create .env file

Copy the example environment file and edit it with your domain:

```bash
cp .env.example .env
```

Edit `.env` and set your domain:
```bash
DOMAIN=your-domain.com
```

### 2. Prepare TLS Certificates

Place your TLS certificates for your domain in the `certs/` directory:
- `certs/your-domain.com.crt` - Certificate file
- `certs/your-domain.com.key` - Private key file

> **Note:** Certificate generation is up to you. You can use self-signed certificates for local testing or certificates from a trusted CA.

> **Important:** The certificate filenames must match your domain name from the `.env` file.

### 3. Configure DNS or Hosts File

The GrapheneOS Auditor app expects to connect to the domain you configured. You must redirect this domain to your local server's IP address.

#### Option A: Local Machine (hosts file)

Edit your hosts file:

**Linux/macOS:**
```bash
sudo nano /etc/hosts
```

**Windows:**
```
C:\Windows\System32\drivers\etc\hosts
```

Add the following line (replace `192.168.1.100` with your server's IP and `your-domain.com` with your domain):
```
192.168.1.100 your-domain.com
```

#### Option B: Network-wide (DNS)

Configure your router or local DNS server (like Pi-hole or AdGuard) to resolve your domain to your server's IP address.

#### Option C: Android Device (root required)

If your Android device is rooted, edit `/system/etc/hosts`:
```bash
su
mount -o remount,rw /system
echo "192.168.1.100 your-domain.com" >> /system/etc/hosts
mount -o remount,ro /system
```

**Important:** You must configure this on the Android device running the Auditor app, not just the server.

### 4. Create Data Directory

Ensure the data directory exists for persistent SQLite storage:

```bash
mkdir -p data
```

## Running the Server

### Build and Start

```bash
docker compose up -d --build
```

This will:
1. Build the AttestationServer from source with your configured domain
2. Start the attestation service on port 8080 (internal)
3. Start Caddy reverse proxy on ports 80 and 443

### Check Status

```bash
docker compose ps
docker compose logs -f
```

### Stop the Server

```bash
docker compose down
```

### Stop and Remove All Data

```bash
docker compose down -v
rm -rf data/*.db data/*.db-*
```

## Usage

1. Ensure your Android device has your domain pointing to your server IP
2. Install [GrapheneOS Auditor](https://github.com/GrapheneOS/Auditor) app on your Android device
3. Open the Auditor app
4. The app will connect to your local attestation server instead of the official one

## Directory Structure

```
.
├── certs/                  # TLS certificates
│   ├── your-domain.com.crt
│   └── your-domain.com.key
├── data/                   # SQLite databases (persistent)
│   ├── attestation.db
│   └── samples.db
├── .env                    # Environment configuration (domain settings)
├── .env.example            # Example environment file
├── Caddyfile               # Caddy reverse proxy config
├── Dockerfile              # AttestationServer build
├── docker-compose.yml      # Service orchestration
├── entrypoint.sh           # Container entrypoint
└── process-static-docker.sh # Static file processor
```

## Default Domain

If you don't create a `.env` file, the default domain `attestation.app` will be used for backward compatibility.

## Security Considerations

- Keep your private key (`certs/*.key`) secure and never commit it to version control
- The `.gitignore` file excludes sensitive files like certificates and databases
- This setup is intended for **local/private use only**
- For production deployment, use properly signed certificates from a trusted CA

## License

This Docker setup follows the same license as the upstream [GrapheneOS AttestationServer](https://github.com/GrapheneOS/AttestationServer).