GrapheneOS-AttestationServer-Docker/README.md

GrapheneOS AttestationServer Docker

Dockerized deployment of 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:

cp .env.example .env

Edit .env and set your domain:

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:

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:

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:

mkdir -p data

Running the Server

Build and Start

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

docker compose ps
docker compose logs -f

Stop the Server

docker compose down

Stop and Remove All Data

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