Merge pull request #28 from Dstack-TEE/ingress

Better custom domain example

Author: h4x3rotab

custom-domain/README.md

@@ -0,0 +1,33 @@
+FROM nginx@sha256:b6653fca400812e81569f9be762ae315db685bc30b12ddcdc8616c63a227d3ca
+
+# Use a specific Debian snapshot for reproducible builds
+RUN set -e; \
+    # Create a sources.list file pointing to a specific snapshot
+    echo 'deb [check-valid-until=no] https://snapshot.debian.org/archive/debian/20250411T024939Z bookworm main' > /etc/apt/sources.list && \
+    echo 'deb [check-valid-until=no] https://snapshot.debian.org/archive/debian-security/20250411T024939Z bookworm-security main' >> /etc/apt/sources.list && \
+    echo 'Acquire::Check-Valid-Until "false";' > /etc/apt/apt.conf.d/10no-check-valid-until && \
+    # Install packages with exact versions for reproducibility
+    apt-get -o Acquire::Check-Valid-Until=false update && \
+    apt-get install -y --no-install-recommends \
+        certbot=2.1.0-4 \
+        openssl=3.0.15-1~deb12u1 \
+        bash=5.2.15-2+b7 \
+        python3=3.11.2-1+b1 \
+        python3-pip=23.0.1+dfsg-1 \
+        python3-requests=2.28.1+dfsg-1 \
+        python3.11-venv=3.11.2-6+deb12u5 \
+        curl=7.88.1-10+deb12u12 \
+        jq=1.6-2.1 \
+        coreutils=9.1-1 && \
+        rm -rf /var/lib/apt/lists/* /var/log/* /var/cache/ldconfig/aux-cache
+
+
+RUN mkdir -p /etc/letsencrypt /var/www/certbot /usr/share/nginx/html
+
+COPY ./scripts/* /scripts/
+RUN chmod +x /scripts/*
+ENV PATH="/scripts:$PATH"
+
+ENTRYPOINT ["/scripts/entrypoint.sh"]
+CMD ["nginx", "-g", "daemon off;"]
+

custom-domain/docker-compose.yaml

@@ -0,0 +1,155 @@
+# Custom Domain Setup for dstack Applications
+
+This repository provides a solution for setting up custom domains with automatic SSL certificate management for dstack applications using Cloudflare DNS and Let's Encrypt.
+
+## Overview
+
+This project enables you to run dstack applications with your own custom domain, complete with:
+
+- Automatic SSL certificate provisioning and renewal via Let's Encrypt
+- Cloudflare DNS configuration for CNAME, TXT, and CAA records
+- Nginx reverse proxy to route traffic to your application
+- Certificate evidence generation for verification
+
+## How It Works
+
+The dstack-ingress system provides a seamless way to set up custom domains for dstack applications with automatic SSL certificate management. Here's how it works:
+
+1. **Initial Setup**:
+   - When first deployed, the container automatically obtains SSL certificates from Let's Encrypt using DNS validation
+   - It configures Cloudflare DNS by creating necessary CNAME, TXT, and optional CAA records
+   - Nginx is configured to use the obtained certificates and proxy requests to your application
+
+2. **DNS Configuration**:
+   - A CNAME record is created to point your custom domain to the dstack gateway domain
+   - A TXT record is added with application identification information to help dstack-gateway to route traffic to your application
+   - If enabled, CAA records are set to restrict which Certificate Authorities can issue certificates for your domain
+
+3. **Certificate Management**:
+   - SSL certificates are automatically obtained during initial setup
+   - A scheduled task runs twice daily to check for certificate renewal
+   - When certificates are renewed, Nginx is automatically reloaded to use the new certificates
+
+4. **Evidence Generation**:
+   - The system generates evidence files for verification purposes
+   - These include the ACME account information and certificate data
+   - Evidence files are accessible through a dedicated endpoint
+
+## Usage
+
+### Prerequisites
+
+- Host your domain on Cloudflare and have access to the Cloudflare account with API token
+
+### Deployment
+
+You can either build the ingress container and push it to docker hub, or use the prebuilt image at `kvin/dstack-ingress`.
+
+#### Option 1: Use the Pre-built Image
+
+The fastest way to get started is to use our pre-built image. Simply use the following docker-compose configuration:
+
+```yaml
+services:
+  dstack-ingress:
+    image: kvin/dstack-ingress@sha256:8dfc3536d1bd0be0cb938140aeff77532d35514ae580d8bec87d3d5a26a21470
+    ports:
+      - "443:443"
+    environment:
+      - CLOUDFLARE_API_TOKEN=${CLOUDFLARE_API_TOKEN}
+      - DOMAIN=${DOMAIN}
+      - GATEWAY_DOMAIN=${GATEWAY_DOMAIN}
+      - CERTBOT_EMAIL=${CERTBOT_EMAIL}
+      - SET_CAA=true
+      - TARGET_ENDPOINT=http://app:80
+    volumes:
+      - /var/run/tappd.sock:/var/run/tappd.sock
+      - cert-data:/etc/letsencrypt
+    restart: unless-stopped
+  app:
+    image: nginx  # Replace with your application image
+    restart: unless-stopped
+volumes:
+  cert-data:  # Persistent volume for certificates
+```
+
+Explanation of environment variables:
+
+- `CLOUDFLARE_API_TOKEN`: Your Cloudflare API token
+- `DOMAIN`: Your custom domain
+- `GATEWAY_DOMAIN`: The dstack gateway domain. (e.g. `_.dstack-prod5.phala.network` for Phala Cloud)
+- `CERTBOT_EMAIL`: Your email address used in Let's Encrypt certificate requests
+- `TARGET_ENDPOINT`: The plain HTTP endpoint of your dstack application
+- `SET_CAA`: Set to `true` to enable CAA record setup
+
+#### Option 2: Build Your Own Image
+
+If you prefer to build the image yourself:
+
+1. Clone this repository
+2. Build the Docker image:
+
+```bash
+docker build -t yourusername/dstack-ingress .
+```
+
+3. Push to your registry (optional):
+
+```bash
+docker push yourusername/dstack-ingress
+```
+
+4. Update the docker-compose.yaml file with your image name and deploy
+
+## Domain Attestation and Verification
+
+The dstack-ingress system provides mechanisms to verify and attest that your custom domain endpoint is secure and properly configured. This comprehensive verification approach ensures the integrity and authenticity of your application.
+
+### Evidence Collection
+
+When certificates are issued or renewed, the system automatically generates a set of cryptographically linked evidence files:
+
+1. **Access Evidence Files**:
+   - Evidence files are accessible at `https://your-domain.com/evidences/`
+   - Key files include `acme-account.json`, `cert.pem`, `sha256sum.txt`, and `quote.json`
+
+2. **Verification Chain**:
+   - `quote.json` contains a TDX quote with the SHA-256 digest of `sha256sum.txt` embedded in the report_data field
+   - `sha256sum.txt` contains cryptographic checksums of both `acme-account.json` and `cert.pem`
+   - When the TDX quote is verified, it cryptographically proves the integrity of the entire evidence chain
+
+3. **Certificate Authentication**:
+   - `acme-account.json` contains the ACME account credentials used to request certificates
+   - When combined with the CAA DNS record, this provides evidence that certificates can only be requested from within this specific TEE application
+   - `cert.pem` is the Let's Encrypt certificate currently serving your custom domain
+
+### CAA Record Verification
+
+If you've enabled CAA records (`SET_CAA=true`), you can verify that only authorized Certificate Authorities can issue certificates for your domain:
+
+```bash
+dig CAA your-domain.com
+```
+
+The output will display CAA records that restrict certificate issuance exclusively to Let's Encrypt with your specific account URI, providing an additional layer of security.
+
+### TLS Certificate Transparency
+
+All Let's Encrypt certificates are logged in public Certificate Transparency (CT) logs, enabling independent verification:
+
+**CT Log Verification**:
+   - Visit [crt.sh](https://crt.sh/) and search for your domain
+   - Confirm that the certificates match those issued by the dstack-ingress system
+   - This public logging ensures that all certificates are visible and can be monitored for unauthorized issuance
+
+## License
+
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

custom-domain/dstack-ingress/Dockerfile

@@ -0,0 +1,11 @@
+#!/bin/bash
+NAME=$1
+if [ -z "$NAME" ]; then
+    echo "Usage: $0 <name>[:<tag>]"
+    exit 1
+fi
+# Check if buildkit_20 already exists before creating it
+if ! docker buildx inspect buildkit_20 &>/dev/null; then
+    docker buildx create --use --driver-opt image=moby/buildkit:v0.20.2 --name buildkit_20
+fi
+docker buildx build --builder buildkit_20 --no-cache --build-arg SOURCE_DATE_EPOCH="0" --output type=docker,name=$NAME,rewrite-timestamp=true .

custom-domain/dstack-ingress/README.md

@@ -0,0 +1,24 @@
+services:
+  dstack-ingress:
+    image: kvin/dstack-ingress@sha256:5cbf6eff9983fad4018de90ed11b0593c84f2022ddfc64b9eb513d1ba79970c7
+    ports:
+      - "443:443"
+    environment:
+      - CLOUDFLARE_API_TOKEN=${CLOUDFLARE_API_TOKEN}
+      - DOMAIN=${DOMAIN}
+      - GATEWAY_DOMAIN=${GATEWAY_DOMAIN}
+      - CERTBOT_EMAIL=${CERTBOT_EMAIL}
+      - SET_CAA=true
+      - TARGET_ENDPOINT=http://app:80
+    volumes:
+      - /var/run/tappd.sock:/var/run/tappd.sock
+      - cert-data:/etc/letsencrypt
+    restart: unless-stopped
+
+  app:
+    image: nginx
+    restart: unless-stopped
+
+volumes:
+  cert-data:
+