### Development Quickstart

Source: https://github.com/bluesky-social/ozone/blob/main/README.md

Starts the Ozone development server using npm or yarn. Requires Node.js v20 and yarn.

```javascript
npm run dev
# or
yarn dev
```

--------------------------------

### Docker Quickstart

Source: https://github.com/bluesky-social/ozone/blob/main/README.md

Builds the Ozone Docker image and runs the container, exposing the application on port 3000.

```bash
# build image
docker build -t ozone .

# run the image
docker run -p 3000:3000 ozone
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Runs a simple 'hello-world' container to confirm Docker is installed and functioning correctly.

```bash
sudo docker run hello-world
```

--------------------------------

### Manage Ozone systemd Service

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Commands to reload the systemd daemon, enable the Ozone service to start on boot, and start the service.

```bash
sudo systemctl daemon-reload
sudo systemctl enable ozone
sudo systemctl start ozone
```

--------------------------------

### Local Development Setup Commands

Source: https://github.com/bluesky-social/ozone/blob/main/HACKING.md

Commands to set up a local development environment for Ozone, including running the PDS dev server and the Ozone frontend.

```bash
yarn workspace @atproto/dev-env start
```

```bash
yarn dev
```

--------------------------------

### Install Docker CE on Ubuntu 22.04

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Installs Docker Community Edition (CE) on Ubuntu 22.04. This process involves uninstalling old versions, setting up the Docker repository, and installing the necessary Docker packages.

```bash
sudo apt-get remove docker docker-engine docker.io containerd runc
sudo apt-get update
sudo apt-get install \
    ca-certificates \
    curl \
    jq \
    openssl \
    xxd \
    gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=\"$(dpkg --print-architecture)\" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  \"$(. /etc/os-release && echo \"$VERSION_CODENAME\")\" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

--------------------------------

### Create systemd Service for Ozone

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Defines a systemd service unit to manage the Ozone Docker containers, allowing for easy starting, stopping, and status checking.

```bash
cat <<SYSTEMD_UNIT_FILE | sudo tee /etc/systemd/system/ozone.service
[Unit]
Description=Bluesky Ozone Service
Documentation=https://github.com/bluesky-social/ozone
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/ozone
ExecStart=/usr/bin/docker compose --file /ozone/compose.yaml up --detach
ExecStop=/usr/bin/docker compose --file /ozone/compose.yaml down

[Install]
WantedBy=default.target
SYSTEMD_UNIT_FILE
```

--------------------------------

### Next.js API Route Example

Source: https://github.com/bluesky-social/ozone/blob/main/HACKING.md

Demonstrates how to access and modify a Next.js API route. The `/api/hello` endpoint is mapped to `pages/api/hello.ts` and can be accessed at `http://localhost:3000/api/hello`.

```typescript
pages/index.tsx

// You can start editing the page by modifying this file.
// The page auto-updates as you edit the file.
```

```typescript
pages/api/hello.ts

// This endpoint can be edited in pages/api/hello.ts.
// The pages/api directory is mapped to /api/*.
```

--------------------------------

### Check Ozone Server Health

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Verifies if the Ozone server is online and healthy by querying the healthcheck endpoint. It also shows an example of the expected JSON response.

```bash
curl https://ozone.EXAMPLE.COM/xrpc/_health
{"version":"0.1.1"}
```

--------------------------------

### Email Template Variables and Comments

Source: https://github.com/bluesky-social/ozone/blob/main/docs/userguide.md

Demonstrates how to use variables and comments within email templates for personalized messaging and content placeholders. Variables are enclosed in double brackets, and comments in triple quotes.

```English
Email templates can include a small number of variables in double-brackets, like `{{handle}}`, which will expand the the relevant account's handle when the message is actually sent. It is also possible to include triple-quote template comments like `### DESCRIPTION OF IMAGE ###`. These will not be auto-substituted, but the mail will not be sent until this placeholder has been replaced (or an override is toggled).
```

--------------------------------

### Infrastructure-Level Moderation Actions

Source: https://github.com/bluesky-social/ozone/blob/main/docs/userguide.md

Details advanced moderation actions available at the infrastructure level, typically requiring specific system configurations and permissions. These actions impact content and accounts at a more fundamental level.

```text
- InfraTakedown: a takedown at the infrastructure level, for example at a PDS, Relay, or AppView. requires the infrastructure to respect the authority of the moderation service.
- Divert: forwards potentially harmful content from Ozone in to a configured external review system, and removes the content from public access and infrastructure. Used primarily for illegal child abuse imagery.
```

--------------------------------

### Ozone Moderation Actions

Source: https://github.com/bluesky-social/ozone/blob/main/docs/userguide.md

Lists the available actions for an independent labeling service within the Ozone system. These actions range from acknowledging reports to applying labels and managing account status.

```text
- Acknowledge: resolves open reports on a subject with no other action
- Escalate: moves subject to the "Escalation" queue, for additional feedback and consideration from the rest of the team
- Label: adds or removes labels from the subject
- Tag: adds or removes tags on the subject. Tags are metadata visible to the entire team, but not publicly visible, including to the subject of the tag.
- Mute: temporarily removes the subject from the "Unreviewed" queue, even if new reports are filed
- Comment: adds a team-private comment about the subject, used for coordination
- Appeal (and Resolve Appeal): a way to manually indicate that the subject has appealed an action (for example, if they appealed via email while account is taken down)
- Takedown (and Reverse Takedown): marks the account as takendown. The scope and impact of this decision will depend on the users and services subscribing to the moderation service
```

--------------------------------

### Embedded Tetris Game in Ozone

Source: https://github.com/bluesky-social/ozone/blob/main/docs/userguide.md

Ozone includes a hidden Tetris game accessible via the control panel. This feature is a small affordance for moderators who may encounter disturbing content, offering a brief mental break.

```text
Open the Ctrl-K menu, type "tetris", and press enter.
```

--------------------------------

### Set Up Ozone Directories

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Creates the necessary directory structure for Ozone, Postgres, and Caddy configurations.

```bash
sudo mkdir /ozone
sudo mkdir /ozone/postgres
sudo mkdir --parents /ozone/caddy/data
sudo mkdir --parents /ozone/caddy/etc/caddy
```

--------------------------------

### Create Caddyfile for Reverse Proxy

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Configures Caddy as a reverse proxy for the Ozone service, handling TLS certificates and domain routing. Replace `ozone.example.com` and `ozone@example.com` with your specific domain and email.

```bash
cat <<CADDYFILE | sudo tee /ozone/caddy/etc/caddy/Caddyfile
ozone.example.com {
  tls ozone@example.com
  reverse_proxy http://localhost:3000
}
CADDYFILE
```

--------------------------------

### Create Postgres Environment Configuration

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Sets up the environment file for the Postgres container, defining user, password, and database name. A random password is generated for security.

```bash
POSTGRES_PASSWORD="$(openssl rand --hex 16)"

cat <<POSTGRES_CONFIG | sudo tee /ozone/postgres.env
POSTGRES_USER=postgres
POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
POSTGRES_DB=ozone
POSTGRES_CONFIG
```

--------------------------------

### Download Docker Compose File

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Downloads the `compose.yaml` file required to orchestrate the Ozone, Postgres, Caddy, and Watchtower Docker containers.

```bash
curl https://raw.githubusercontent.com/bluesky-social/ozone/main/service/compose.yaml | sudo tee /ozone/compose.yaml
```

--------------------------------

### Create Ozone Environment Configuration

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Generates the environment file for the Ozone service. This includes essential configurations like hostname, service account, admin credentials, signing key, and database connection details. It also fetches the server DID from the AT Protocol identity service.

```bash
OZONE_HOSTNAME="ozone.example.com"
OZONE_SERVICE_ACCOUNT_HANDLE="mylabeler.bsky.social"
OZONE_SERVER_DID="$(curl --fail --silent --show-error "https://api.bsky.app/xrpc/com.atproto.identity.resolveHandle?handle=${OZONE_SERVICE_ACCOUNT_HANDLE}" | jq --raw-output .did)"
OZONE_ADMIN_PASSWORD="$(openssl rand --hex 16)"
OZONE_SIGNING_KEY_HEX="$(openssl ecparam --name secp256k1 --genkey --noout --outform DER | tail --bytes=+8 | head --bytes=32 | xxd --plain --cols 32)"
POSTGRES_PASSWORD="..." # Use password from postgres env setup

cat <<OZONE_CONFIG | sudo tee /ozone/ozone.env
OZONE_SERVER_DID=${OZONE_SERVER_DID}
OZONE_PUBLIC_URL=https://${OZONE_HOSTNAME}
OZONE_ADMIN_DIDS=${OZONE_SERVER_DID}
OZONE_ADMIN_PASSWORD=${OZONE_ADMIN_PASSWORD}
OZONE_SIGNING_KEY_HEX=${OZONE_SIGNING_KEY_HEX}
OZONE_DB_POSTGRES_URL=postgresql://postgres:${POSTGRES_PASSWORD}@localhost:5432/ozone
OZONE_DB_MIGRATE=1
OZONE_DID_PLC_URL=https://plc.directory
OZONE_APPVIEW_URL=https://api.bsky.app
OZONE_APPVIEW_DID=did:web:api.bsky.app
LOG_ENABLED=1
OZONE_CONFIG
```

--------------------------------

### Working with Unpublished @atproto/api Package

Source: https://github.com/bluesky-social/ozone/blob/main/HACKING.md

Workflow for using local, unpublished changes to the `@atproto/api` package with the Ozone project. This involves linking the local package build.

```bash
cd atproto
git checkout main
yarn
```

```json
{
  "dependencies": {
    "@atproto/api": "link:../atproto/packages/api/dist",
    "@headlessui/react": "^1.7.7"
  }
}
```

```bash
yarn
git checkout package.json yarn.lock && yarn
```

--------------------------------

### Restart Ozone Service

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Restarts the Ozone service after a manual update to apply the new container image.

```bash
sudo systemctl restart ozone
```

--------------------------------

### Ozone Environment Variables Configuration

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Lists and describes essential environment variables for configuring an Ozone instance. This includes settings for the server DID, public URL, admin access, signing keys, database connection, and more. Some variables are critical for operation and should be modified, while others are typically left at their default values.

```APIDOC
Ozone Environment Variables:

- OZONE_SERVER_DID: The DID of your Ozone service account. Should modify.
  Example: did:plc:39dak...
- OZONE_PUBLIC_URL: Publicly accessible URL to your Ozone service. Should modify.
  Example: https://ozone.example.com
- OZONE_ADMIN_DIDS: Comma-separated list of DIDs granted access to login to your Ozone service. Should modify.
  Example: did:plc:39...,did:plc:f7...
- OZONE_ADMIN_PASSWORD: Admin password for API key access. Should modify.
  Example: 3ee68...
- OZONE_SIGNING_KEY_HEX: Hex representation of a private key for signing labels. Should modify.
  Example: e049f...
- OZONE_DB_POSTGRES_URL: PostgreSQL connection URL with credentials. Should modify.
  Example: postgresql://pg:password...
- OZONE_DB_MIGRATE: Perform DB migrations at startup. Do not modify.
  Value: 1
- OZONE_DID_PLC_URL: URL for PLC identity lookups. Do not modify.
  Value: https://plc.directory
- OZONE_APPVIEW_URL: URL to communicate with the appview. Do not modify.
  Example: https://api.bsky.app
- OZONE_APPVIEW_DID: DID to communicate with the appview. Do not modify.
  Example: did:web:api.bsky.app
- LOG_ENABLED: Enable JSON log output. Do not modify.
  Value: 1
```

--------------------------------

### Check WebSocket Label Stream

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Tests the WebSocket label stream functionality to ensure labels are being published correctly. This command may run with no output if configured successfully and no labels have been created yet.

```bash
wsdump "wss://ozone.EXAMPLE.COM/xrpc/com.atproto.label.subscribeLabels?cursor=0"
```

--------------------------------

### Check Ozone Service Status

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Verifies that the Ozone systemd service is running and checks the status of all running Docker containers.

```bash
sudo systemctl status ozone
sudo docker ps
```

--------------------------------

### Pull Latest Ozone Container Image

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Manually updates the Ozone service by pulling the latest container image from the Docker registry.

```docker
sudo docker pull ghcr.io/bluesky-social/ozone:latest
```

--------------------------------

### AT Protocol Identity API - Resolve Handle

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

An API endpoint to resolve a user's handle to their Decentralized Identifier (DID). This is used to fetch the `OZONE_SERVER_DID`.

```APIDOC
GET /xrpc/com.atproto.identity.resolveHandle

---

**Description:**
Resolves a handle to a DID.

**Parameters:**
- `handle` (string, required): The user's handle (e.g., `mylabeler.bsky.social`).

**Returns:**
- `did` (string): The Decentralized Identifier (DID) associated with the handle.

**Example Usage:**
```bash
curl --fail --silent --show-error "https://api.bsky.app/xrpc/com.atproto.identity.resolveHandle?handle=mylabeler.bsky.social"
```

**Error Conditions:**
- Returns an error if the handle is not found or the service is unavailable.
```

--------------------------------

### Ozone Moderation Query Endpoints

Source: https://github.com/bluesky-social/ozone/blob/main/docs/api.md

Provides access to moderation statuses and events. The `queryStatuses` endpoint allows filtering and sorting of subjects requiring review, while `queryEvents` retrieves historical moderation actions. The `emitEvent` endpoint is used by moderators to record actions.

```APIDOC
tools.ozone.moderation.queryStatuses(includeMuted: boolean = false, ...filters)
  - Retrieves a list of subjects that have received a report or been moderated.
  - Parameters:
    - includeMuted: If true, includes muted subjects in the results (default: false).
    - ...filters: Various parameters to filter and sort the queue (e.g., by review status, appeals, escalated subjects).
  - Returns: A list of subject statuses.

tools.ozone.moderation.queryEvents(subject: string, includeAllUserRecords: boolean = false, ...filters)
  - Retrieves historical moderation events.
  - Parameters:
    - subject: The subject (content or user DID) to query events for.
    - includeAllUserRecords: If true, retrieves all moderation events for all content/subjects belonging to the specified user DID (default: false).
    - ...filters: Various parameters to filter the event data.
  - Returns: A list of moderation events.

tools.ozone.moderation.emitEvent(subject: string, action: string, role: 'triage' | 'moderator' | 'admin', ...details)
  - Records a moderation action taken by a moderator.
  - Parameters:
    - subject: The subject of the moderation action.
    - action: The type of action taken (e.g., 'takedown', 'label').
    - role: The role of the user performing the action ('triage', 'moderator', or 'admin').
    - ...details: Additional information about the event.
  - Returns: Confirmation of event emission.
```

--------------------------------

### Open Ports on Linux Firewall

Source: https://github.com/bluesky-social/ozone/blob/main/HOSTING.md

Opens ports 80/tcp and 443/tcp on the server's Linux firewall using ufw. These ports are required for TLS certification verification and application requests, respectively.

```bash
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
```

--------------------------------

### Ozone Moderation Subject States

Source: https://github.com/bluesky-social/ozone/blob/main/docs/api.md

Describes the possible states for a subject within the Ozone moderation system, including reviewOpen, reviewEscalated, reviewClosed, and reviewNone. These states track the subject's progress through the reporting and review cycle.

```APIDOC
reviewState:
  - reviewOpen: Subject has incoming reports and requires review.
  - reviewEscalated: Subject requires review by higher-tier moderators.
  - reviewClosed: Subject has been reviewed, with or without action.
  - reviewNone: Subject has metadata stored but requires no human review.
```

--------------------------------

### Ozone API Query Subjects

Source: https://github.com/bluesky-social/ozone/blob/main/docs/api.md

Details the API endpoint for querying subjects within the Ozone moderation system. This endpoint allows filtering subjects based on various metadata and states, often used to populate moderation queues.

```APIDOC
tools.ozone.moderation.querySubjects:
  description: Retrieves a list of subjects based on specified criteria.
  parameters:
    - queue: Filters subjects by their state in moderation queues.
    - filter: Additional filtering options for subjects.
  returns:
    - A list of subjects matching the query criteria.
```

--------------------------------

### Ozone Moderation Subject Properties

Source: https://github.com/bluesky-social/ozone/blob/main/docs/api.md

Details the boolean state properties for subjects in the Ozone moderation system: muted, appealed, and takendown. These properties indicate specific moderation statuses and actions taken on a subject.

```APIDOC
muted: Boolean indicating if the subject is temporarily excluded from moderation queues.
appealed: Boolean indicating if the author has appealed a moderation decision.
takendown: Boolean indicating if the subject has been temporarily or permanently taken down.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.