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 `attestation.app` domain in the `certs/` directory:
   - `certs/attestation.app.crt` - Certificate file
   - `certs/attestation.app.key` - Private key file
3. **DNS or hosts file configuration** to resolve `attestation.app` to your server

## Pre-Launch Setup

### 1. Prepare TLS Certificates

Place your TLS certificates for `attestation.app` in the `certs/` directory:
- `certs/attestation.app.crt` - Certificate
- `certs/attestation.app.key` - Private key

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

### 2. Configure DNS or Hosts File

The GrapheneOS Auditor app expects to connect to `attestation.app`. 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):
```
192.168.1.100 attestation.app
```

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

Configure your router or local DNS server (like Pi-hole or AdGuard) to resolve `attestation.app` 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 attestation.app" >> /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.

### 3. 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
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 `attestation.app` 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
│   ├── attestation.app.crt
│   └── attestation.app.key
├── data/                   # SQLite databases (persistent)
│   ├── attestation.db
│   └── samples.db
├── Caddyfile               # Caddy reverse proxy config
├── Dockerfile              # AttestationServer build
├── docker-compose.yml      # Service orchestration
├── entrypoint.sh           # Container entrypoint
└── process-static-docker.sh # Static file processor
```


## Security Considerations

- Keep your private key (`certs/attestation.app.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).