contrib,nix: local, sandboxed atmosphere infra

Add sandboxed atmosphere environment for local testing. This new vm
contains everything required to run local test appview including PLC,
PDS, Jetstream (listening to single PDS), knot and spindle.

I'm using my custom `tngl.boltless.dev` domain which resolves to
`127.0.0.1` without any proxy.

PLC: plc.tngl.boltless.dev
PDS: pds.tngl.boltless.dev
Relay: relay.tngl.boltless.dev
Jetstream: jetstream.tngl.boltless.dev
Knot: knot.tngl.boltless.dev
Spindle: spindle.tngl.boltless.dev

TLS is supported with caddy service running inside the vm.

note: `pds.env` file here is hard copy to be used for contrib/scripts.
note: upgraded pds package in order to set email settings

Signed-off-by: Seongmin Lee <[e-mail]>

contrib/certs/root.crt

···
+-----BEGIN CERTIFICATE-----
+MIIBpDCCAUmgAwIBAgIQKU9d61/WZ56BCZVYfEC6sTAKBggqhkjOPQQDAjAwMS4w
+LAYDVQQDEyVDYWRkeSBMb2NhbCBBdXRob3JpdHkgLSAyMDI1IEVDQyBSb290MB4X
+DTI1MTIxNDE4MTgzNVoXDTM1MTAyMzE4MTgzNVowMDEuMCwGA1UEAxMlQ2FkZHkg
+TG9jYWwgQXV0aG9yaXR5IC0gMjAyNSBFQ0MgUm9vdDBZMBMGByqGSM49AgEGCCqG
+SM49AwEHA0IABPvHcpXJqjBY65eTkPvOVrYU7hG3mUHo2uKLNk4UU5pp0u8f0Lnr
+qGfdnsE0OI5p/+VPlwWJADZYAU3sr6+wkRajRTBDMA4GA1UdDwEB/wQEAwIBBjAS
+BgNVHRMBAf8ECDAGAQH/AgEBMB0GA1UdDgQWBBRdJ3V1QlZggp4ajYwGyLC6lNzq
+JzAKBggqhkjOPQQDAgNJADBGAiEAr0hlnlWKC5PQXeguOcaEZZN/2+yxc5GdQTfv
+66DO4XICIQC6yZaLrKjwPlghYsgT2ysgnboJTfrpwrO4+Naa5leZNg==
+-----END CERTIFICATE-----

contrib/example.env

···
+# NOTE: put actual DIDs here
+alice_did=did:plc:alice-did
+tangled_did=did:plc:tangled-did
+
+#core
+export TANGLED_DEV=true
+export TANGLED_APPVIEW_HOST=http://127.0.0.1:3000
+# plc
+export TANGLED_PLC_URL=https://plc.tngl.boltless.dev
+# jetstream
+export TANGLED_JETSTREAM_ENDPOINT=wss://jetstream.tngl.boltless.dev/subscribe
+# label
+export TANGLED_LABEL_GFI=at://${tangled_did}/sh.tangled.label.definition/good-first-issue
+export TANGLED_LABEL_DEFAULTS=$TANGLED_LABEL_GFI
+export TANGLED_LABEL_DEFAULTS=$TANGLED_LABEL_DEFAULTS,at://${tangled_did}/sh.tangled.label.definition/assignee
+export TANGLED_LABEL_DEFAULTS=$TANGLED_LABEL_DEFAULTS,at://${tangled_did}/sh.tangled.label.definition/documentation
+export TANGLED_LABEL_DEFAULTS=$TANGLED_LABEL_DEFAULTS,at://${tangled_did}/sh.tangled.label.definition/duplicate
+export TANGLED_LABEL_DEFAULTS=$TANGLED_LABEL_DEFAULTS,at://${tangled_did}/sh.tangled.label.definition/wontfix
+
+# vm settings
+export TANGLED_VM_PLC_URL=https://plc.tngl.boltless.dev
+export TANGLED_VM_JETSTREAM_ENDPOINT=wss://jetstream.tngl.boltless.dev/subscribe
+export TANGLED_VM_KNOT_HOST=knot.tngl.boltless.dev
+export TANGLED_VM_KNOT_OWNER=$alice_did
+export TANGLED_VM_SPINDLE_HOST=spindle.tngl.boltless.dev
+export TANGLED_VM_SPINDLE_OWNER=$alice_did
+
+if [ -n "${TANGLED_RESEND_API_KEY:-}" ] && [ -n "${TANGLED_RESEND_SENT_FROM:-}" ]; then
+    export TANGLED_VM_PDS_EMAIL_SMTP_URL=smtps://resend:$[e-mail]:465/
+    export TANGLED_VM_PDS_EMAIL_FROM_ADDRESS=$TANGLED_RESEND_SENT_FROM
+fi

contrib/pds.env

···
+LOG_ENABLED=true
+
+PDS_JWT_SECRET=8cae8bffcc73d9932819650791e4e89a
+PDS_ADMIN_PASSWORD=d6a902588cd93bee1af83f924f60cfd3
+PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX=2e92e336a50a618458e1097d94a1db86ec3fd8829d7735020cbae80625c761d7
+
+PDS_DATA_DIRECTORY=/pds
+PDS_BLOBSTORE_DISK_LOCATION=/pds/blocks
+
+PDS_DID_PLC_URL=http://localhost:8080
+PDS_HOSTNAME=pds.tngl.boltless.dev
+PDS_PORT=3000

contrib/readme.md

···
+# how to setup local appview dev environment
+
+Appview requires several microservices from knot and spindle to entire atproto infra. This test environment is implemented under nixos vm.
+
+1. copy `contrib/example.env` to `.env`, fill it and source it
+2. run vm
+  ```bash
+  nix run --impure .#vm
+  ```
+3. trust the generated cert from host machine
+  ```bash
+  # for macos
+  sudo security add-trusted-cert -d -r trustRoot \
+    -k /Library/Keychains/System.keychain \
+    ./nix/vm-data/caddy/.local/share/caddy/pki/authorities/local/root.crt
+  ```
+4. create test accounts with valid emails (use [`create-test-account.sh`](./scripts/create-test-account.sh))
+5. create default labels (use [`setup-const-records`](./scripts/setup-const-records.sh))
+6. restart vm with correct owner-did
+
+for git-https, you should change your local git config:
+```
+[http "https://knot.tngl.boltless.dev"]
+  sslCAPath = /Users/boltless/repo/tangled/nix/vm-data/caddy/.local/share/caddy/pki/authorities/local/
+```

contrib/scripts/create-test-account.sh

···
+#!/bin/bash
+set -o errexit
+set -o nounset
+set -o pipefail
+
+source "$(dirname "$0")/../pds.env"
+
+# PDS_HOSTNAME=
+# PDS_ADMIN_PASSWORD=
+
+# curl a URL and fail if the request fails.
+function curl_cmd_get {
+  curl --fail --silent --show-error "$@"
+}
+
+# curl a URL and fail if the request fails.
+function curl_cmd_post {
+  curl --fail --silent --show-error --request POST --header "Content-Type: application/json" "$@"
+}
+
+# curl a URL but do not fail if the request fails.
+function curl_cmd_post_nofail {
+  curl --silent --show-error --request POST --header "Content-Type: application/json" "$@"
+}
+
+USERNAME="${1:-}"
+
+if [[ "${USERNAME}" == "" ]]; then
+  read -p "Enter a username: " USERNAME
+fi
+
+if [[ "${USERNAME}" == "" ]]; then
+  echo "ERROR: missing USERNAME parameter." >/dev/stderr
+  echo "Usage: $0 ${SUBCOMMAND} <USERNAME>" >/dev/stderr
+  exit 1
+fi
+
+EMAIL=${USERNAME}@${PDS_HOSTNAME}
+
+PASSWORD="password"
+INVITE_CODE="$(curl_cmd_post \
+  --user "admin:${PDS_ADMIN_PASSWORD}" \
+  --data '{"useCount": 1}' \
+  "https://${PDS_HOSTNAME}/xrpc/com.atproto.server.createInviteCode" | jq --raw-output '.code'
+)"
+RESULT="$(curl_cmd_post_nofail \
+  --data "{\"email\":\"${EMAIL}\", \"handle\":\"${USERNAME}.${PDS_HOSTNAME}\", \"password\":\"${PASSWORD}\", \"inviteCode\":\"${INVITE_CODE}\"}" \
+  "https://${PDS_HOSTNAME}/xrpc/com.atproto.server.createAccount"
+)"
+
+DID="$(echo $RESULT | jq --raw-output '.did')"
+if [[ "${DID}" != did:* ]]; then
+  ERR="$(echo ${RESULT} | jq --raw-output '.message')"
+  echo "ERROR: ${ERR}" >/dev/stderr
+  echo "Usage: $0 <EMAIL> <HANDLE>" >/dev/stderr
+  exit 1
+fi
+
+echo
+echo "Account created successfully!"
+echo "-----------------------------"
+echo "Handle   : ${USERNAME}.${PDS_HOSTNAME}"
+echo "DID      : ${DID}"
+echo "Password : ${PASSWORD}"
+echo "-----------------------------"
+echo "This is a test account with an insecure password."
+echo "Make sure it's only used for development."
+echo

contrib/scripts/setup-const-records.sh

···
+#!/bin/bash
+set -o errexit
+set -o nounset
+set -o pipefail
+
+source "$(dirname "$0")/../pds.env"
+
+# PDS_HOSTNAME=
+
+# curl a URL and fail if the request fails.
+function curl_cmd_get {
+  curl --fail --silent --show-error "$@"
+}
+
+# curl a URL and fail if the request fails.
+function curl_cmd_post {
+  curl --fail --silent --show-error --request POST --header "Content-Type: application/json" "$@"
+}
+
+# curl a URL but do not fail if the request fails.
+function curl_cmd_post_nofail {
+  curl --silent --show-error --request POST --header "Content-Type: application/json" "$@"
+}
+
+USERNAME="${1:-}"
+
+if [[ "${USERNAME}" == "" ]]; then
+  read -p "Enter a username: " USERNAME
+fi
+
+if [[ "${USERNAME}" == "" ]]; then
+  echo "ERROR: missing USERNAME parameter." >/dev/stderr
+  echo "Usage: $0 ${SUBCOMMAND} <USERNAME>" >/dev/stderr
+  exit 1
+fi
+
+SESS_RESULT="$(curl_cmd_post \
+  --data "$(cat <<EOF
+{
+  "identifier": "$USERNAME",
+  "password": "password"
+}
+EOF
+  )" \
+  https://pds.tngl.boltless.dev/xrpc/com.atproto.server.createSession
+)"
+
+echo $SESS_RESULT | jq
+
+DID="$(echo $SESS_RESULT | jq --raw-output '.did')"
+ACCESS_JWT="$(echo $SESS_RESULT | jq --raw-output '.accessJwt')"
+
+function add_label_def {
+  local color=$1
+  local name=$2
+  echo $color
+  echo $name
+  local json_payload=$(cat <<EOF
+{
+  "repo": "$DID",
+  "collection": "sh.tangled.label.definition",
+  "rkey": "$name",
+  "record": {
+    "name": "$name",
+    "color": "$color",
+    "scope": ["sh.tangled.repo.issue"],
+    "multiple": false,
+    "createdAt": "2025-09-22T11:14:35+01:00",
+    "valueType": {"type": "null", "format": "any"}
+  }
+}
+EOF
+)
+  echo $json_payload
+  echo $json_payload | jq
+  RESULT="$(curl_cmd_post \
+    --data "$json_payload" \
+    -H "Authorization: Bearer ${ACCESS_JWT}" \
+    "https://${PDS_HOSTNAME}/xrpc/com.atproto.repo.createRecord")"
+  echo $RESULT | jq
+}
+
+add_label_def '#64748b' 'wontfix'
+add_label_def '#8B5CF6' 'good-first-issue'
+add_label_def '#ef4444' 'duplicate'
+add_label_def '#06b6d4' 'documentation'
+json_payload=$(cat <<EOF
+{
+  "repo": "$DID",
+  "collection": "sh.tangled.label.definition",
+  "rkey": "assignee",
+  "record": {
+    "name": "assignee",
+    "color": "#10B981",
+    "scope": ["sh.tangled.repo.issue", "sh.tangled.repo.pull"],
+    "multiple": false,
+    "createdAt": "2025-09-22T11:14:35+01:00",
+    "valueType": {"type": "string", "format": "did"}
+  }
+}
+EOF
+)
+curl_cmd_post \
+  --data "$json_payload" \
+  -H "Authorization: Bearer ${ACCESS_JWT}" \
+  "https://${PDS_HOSTNAME}/xrpc/com.atproto.repo.createRecord"

flake.nix

···
               rootDir=$(jj --ignore-working-copy root || git rev-parse --show-toplevel) || (echo "error: can't find repo root?"; exit 1)
               cd "$rootDir"
 
-              mkdir -p nix/vm-data/{knot,repos,spindle,spindle-logs}
+              mkdir -p nix/vm-data/{caddy,knot,repos,spindle,spindle-logs}
 
               export TANGLED_VM_DATA_DIR="$rootDir/nix/vm-data"
               exec ${pkgs.lib.getExe

nix/vm.nix

···
   nixpkgs.lib.nixosSystem {
     inherit system;
     modules = [
+      self.nixosModules.did-method-plc
+      self.nixosModules.bluesky-jetstream
+      self.nixosModules.bluesky-relay
       self.nixosModules.knot
       self.nixosModules.spindle
       ({
···
           diskSize = 10 * 1024;
           cores = 2;
           forwardPorts = [
+            # caddy
+            {
+              from = "host";
+              host.port = 80;
+              guest.port = 80;
+            }
+            {
+              from = "host";
+              host.port = 443;
+              guest.port = 443;
+            }
+            {
+              from = "host";
+              proto = "udp";
+              host.port = 443;
+              guest.port = 443;
+            }
             # ssh
             {
               from = "host";
···
             # as SQLite is incompatible with them. So instead we
             # mount the shared directories to a different location
             # and copy the contents around on service start/stop.
+            caddyData = {
+              source = "$TANGLED_VM_DATA_DIR/caddy";
+              target = config.services.caddy.dataDir;
+            };
             knotData = {
               source = "$TANGLED_VM_DATA_DIR/knot";
               target = "/mnt/knot-data";
···
         };
         # This is fine because any and all ports that are forwarded to host are explicitly marked above, we don't need a separate guest firewall
         networking.firewall.enable = false;
+        # resolve `*.tngl.boltless.dev` to host
+        services.dnsmasq.enable = true;
+        services.dnsmasq.settings.address = "/tngl.boltless.dev/10.0.2.2";
+        security.pki.certificates = [
+          (builtins.readFile ../contrib/certs/root.crt)
+        ];
         time.timeZone = "Europe/London";
+        services.timesyncd.enable = lib.mkVMOverride true;
         services.getty.autologinUser = "root";
         environment.systemPackages = with pkgs; [curl vim git sqlite litecli];
+        virtualisation.docker.extraOptions = ''
+          --dns 172.17.0.1
+        '';
         services.tangled.knot = {
           enable = true;
           motd = "Welcome to the development knot!\n";
···
               provider = "sqlite";
             };
           };
+        };
+        services.did-method-plc.enable = true;
+        services.bluesky-pds = {
+          enable = true;
+          # overriding package version to support emails
+          package = pkgs.bluesky-pds.overrideAttrs (old: rec {
+            version = "0.4.188";
+            src = pkgs.fetchFromGitHub {
+              owner = "bluesky-social";
+              repo = "pds";
+              tag = "v${version}";
+              hash = "sha256-t8KdyEygXdbj/5Rhj8W40e1o8mXprELpjsKddHExmo0=";
+            };
+            pnpmDeps = pkgs.pnpm_9.fetchDeps {
+              inherit version src;
+              pname = old.pname;
+              sourceRoot = old.sourceRoot;
+              fetcherVersion = 2;
+              hash = "sha256-lQie7f8JbWKSpoavnMjHegBzH3GB9teXsn+S2SLJHHU=";
+            };
+          });
+          settings = {
+            LOG_ENABLED = "true";
+
+            PDS_JWT_SECRET = "8cae8bffcc73d9932819650791e4e89a";
+            PDS_ADMIN_PASSWORD = "d6a902588cd93bee1af83f924f60cfd3";
+            PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX = "2e92e336a50a618458e1097d94a1db86ec3fd8829d7735020cbae80625c761d7";
+
+            PDS_EMAIL_SMTP_URL = envVarOr "TANGLED_VM_PDS_EMAIL_SMTP_URL" null;
+            PDS_EMAIL_FROM_ADDRESS = envVarOr "TANGLED_VM_PDS_EMAIL_FROM_ADDRESS" null;
+
+            PDS_DID_PLC_URL = "http://localhost:8080";
+            PDS_CRAWLERS = "https://relay.tngl.boltless.dev";
+            PDS_HOSTNAME = "pds.tngl.boltless.dev";
+            PDS_PORT = 3000;
+          };
+        };
+        services.bluesky-relay = {
+          enable = true;
+        };
+        services.bluesky-jetstream = {
+          enable = true;
+          livenessTtl = 300;
+          websocketUrl = "ws://localhost:3000/xrpc/com.atproto.sync.subscribeRepos";
+        };
+        services.caddy = {
+          enable = true;
+          configFile = pkgs.writeText "Caddyfile" ''
+            {
+              debug
+              cert_lifetime 3601d
+              pki {
+                ca local {
+                  intermediate_lifetime 3599d
+                }
+              }
+            }
+
+            plc.tngl.boltless.dev {
+              tls internal
+              reverse_proxy http://localhost:8080
+            }
+
+            *.pds.tngl.boltless.dev, pds.tngl.boltless.dev {
+              tls internal
+              reverse_proxy http://localhost:3000
+            }
+
+            jetstream.tngl.boltless.dev {
+              tls internal
+              reverse_proxy http://localhost:6008
+            }
+
+            relay.tngl.boltless.dev {
+              tls internal
+              reverse_proxy http://localhost:2470
+            }
+
+            knot.tngl.boltless.dev {
+              tls internal
+              reverse_proxy http://localhost:6444
+            }
+
+            spindle.tngl.boltless.dev {
+              tls internal
+              reverse_proxy http://localhost:6555
+            }
+          '';
         };
         users = {
           # So we don't have to deal with permission clashing between