### Quick Start Installation Steps for Rox

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/bare-metal.md

A condensed guide to install Rox, including dependency installation, cloning the repository, building the project, and starting the application.

```bash
# 1. Install dependencies
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc

# 2. Clone and build
git clone https://github.com/your-org/rox.git
cd rox
bun install
bun run build

# 3. Configure (see detailed steps below)

# 4. Start
bun run start
```

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

### Start GoToSocial Server and Setup ngrok

Source: https://github.com/love-rox/rox/blob/main/docs/testing/mastodon-local-setup.md

Start the GoToSocial server in the background and set up ngrok to expose it publicly.

```bash
# Start server
./gotosocial --config-path ./config.yaml server start &

# Setup ngrok
ngrok http 8080
```

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

### Start Development Server

Source: https://github.com/love-rox/rox/blob/main/docs/development/devcontainer.md

After the DevContainer is set up and dependencies are installed, start the development server using Bun.

```bash
bun run dev
```

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

### Development Setup Commands for Rox

Source: https://github.com/love-rox/rox/blob/main/docs/implementation/phase-2-completion.md

Commands to install dependencies, run database migrations, start the development server, and execute tests.

```bash
# Install dependencies
bun install

# Run database migrations
bun run db:migrate

# Start development server
bun run dev

# Run tests
bun test
```

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

### Install and Start PostgreSQL on Ubuntu/Debian

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Install PostgreSQL and its contrib package, then start the service using apt on Ubuntu/Debian systems.

```bash
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
```

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

### Quick Test Setup

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Set up the development environment for integration and E2E tests by starting the server and running tests in separate terminals.

```bash
# Terminal 1 - Start server
cd packages/backend
DB_TYPE=postgres DATABASE_URL="postgresql://rox:rox_dev_password@localhost:5432/rox" bun run dev

# Terminal 2 - Run tests
cd packages/backend
bun test
```

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

### Install and Configure PostgreSQL

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/bare-metal.md

Installs PostgreSQL, starts and enables the service, creates a dedicated user and database for Rox, and tests the connection.

```bash
# Install PostgreSQL 16
sudo apt install -y postgresql postgresql-contrib

# Start and enable service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database and user
sudo -u postgres psql << EOF
CREATE USER rox WITH PASSWORD '${ROX_DB_PASSWORD}';
CREATE DATABASE rox OWNER rox;
GRANT ALL PRIVILEGES ON DATABASE rox TO rox;
EOF

# Test connection
PGPASSWORD="${ROX_DB_PASSWORD}" psql -U rox -h localhost -d rox -c "SELECT 1;"
```

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

### Install and Run Rox Project

Source: https://github.com/love-rox/rox/blob/main/README.md

Steps to clone the repository, install dependencies, configure environment variables, set up development services, run database migrations, and start the development servers for the Rox project.

```bash
git clone https://github.com/Love-Rox/rox.git
cd rox

bun install

cp .env.example .env
# Edit .env with your configuration

docker compose -f docker/compose.dev.yml up -d

bun run db:generate
bun run db:migrate

bun run dev
```

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

### Copy Configuration Files

Source: https://github.com/love-rox/rox/blob/main/docs/testing/misskey-local-setup.md

Copy the example configuration files to be used for the local setup.

```bash
# Copy example files
cp .config/docker_example.yml .config/default.yml
cp .config/docker_example.env .config/docker.env
```

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

### Install and Start PostgreSQL on macOS

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Install PostgreSQL v14 and start the service using Homebrew on macOS.

```bash
brew install postgresql@14
brew services start postgresql@14
```

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

### Start Development Session Commands

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Commands to pull latest changes, install dependencies, start the database, and run the development server.

```bash
git pull origin main

bun install

brew services start postgresql@14

cd packages/backend && bun run dev
```

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

### Install and Configure Caddy

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/bare-metal.md

Installs Caddy and configures it as a reverse proxy for Rox, enabling automatic HTTPS and security headers. Use this for a recommended, hassle-free setup.

```bash
# Install Caddy
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

# Configure Caddy
sudo tee /etc/caddy/Caddyfile > /dev/null << EOF
${ROX_DOMAIN} {
    reverse_proxy localhost:3000

    header {
        # Security headers
        X-Content-Type-Options "nosniff"
        X-Frame-Options "DENY"
        Referrer-Policy "strict-origin-when-cross-origin"
        -Server
    }

    # Enable compression
    encode gzip

    # Logging
    log {
        output file /var/log/caddy/rox.log
    }
}
EOF

# Restart Caddy
sudo systemctl restart caddy
```

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

### Start PostgreSQL Service

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Commands to start the PostgreSQL service depending on your operating system or environment. Use the appropriate command for your setup.

```bash
# macOS
brew services start postgresql@14

# Ubuntu/Debian
sudo systemctl start postgresql

# Docker
docker start rox-postgres
```

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

### Build and Start Misskey Services

Source: https://github.com/love-rox/rox/blob/main/docs/testing/misskey-local-setup.md

Build the Docker image, initialize the database, and start all Misskey services in detached mode.

```bash
# Build Docker image (takes 10-15 minutes)
docker-compose build

# Initialize database
docker-compose run --rm web pnpm run init

# Start all services
docker-compose up -d

# Check status
docker-compose ps
```

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

### Run Frontend in Development Mode

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Navigate to the frontend package and start the development server.

```bash
cd packages/frontend
bun run dev
```

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

### Minimal Production Environment Configuration

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/environment-variables.md

Example INI configuration for a minimal production setup. Ensure sensitive values like POSTGRES_PASSWORD are kept secure.

```ini
ROX_URL=https://rox.example.com
ROX_DOMAIN=rox.example.com
POSTGRES_PASSWORD=your-secure-password
ACME_EMAIL=admin@example.com
ENABLE_REGISTRATION=false
```

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

### Create Application User and Install Bun

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/installation-guide.md

Creates a dedicated user 'rox' with a home directory and installs Bun for this user. Includes verification.

```bash
# Create rox user with home directory at /opt/rox
sudo useradd -r -m -d /opt/rox -s /bin/bash rox

# Install Bun for the rox user
sudo -u rox bash -c 'curl -fsSL https://bun.sh/install | bash'

# Verify bun installation
sudo -u rox /opt/rox/.bun/bin/bun --version
```

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

### Install Project Dependencies

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Install all necessary backend and frontend dependencies for the monorepo using bun.

```bash
bun install
```

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

### Start and Initialize Misskey Services

Source: https://github.com/love-rox/rox/blob/main/docs/testing/misskey-local-setup.md

Commands to create necessary directories, start the Docker services, and initialize the Misskey database. The initialization step is typically performed only once.

```bash
# Create config directory
mkdir -p config files

# Start services
docker-compose up -d

# Initialize database (first time only)
docker-compose exec web pnpm run init
```

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

### Misskey Configuration Example

Source: https://github.com/love-rox/rox/blob/main/docs/testing/misskey-local-setup.md

Example configuration for a local Misskey instance, including URL, port, database, and Redis settings.

```yaml
url: https://misskey.local  # Will be updated with ngrok URL later

port: 3000

# PostgreSQL configuration
db:
  host: db
  port: 5432
  db: misskey
  user: misskey
  pass: misskey_password

# Redis configuration
redis:
  host: redis
  port: 6379

# File storage
drive:
  storage: 'fs'  # Use filesystem for testing

# ID generation
id: 'aid'  # Use AID (recommended)
```

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

### Start Rox Server

Source: https://github.com/love-rox/rox/blob/main/docs/testing/local-https-setup.md

Starts the Rox backend server using 'bun run dev' after navigating to the correct directory.

```bash
cd ~/rox/packages/backend
bun run dev
```

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

### Install Caddy using Homebrew

Source: https://github.com/love-rox/rox/blob/main/docs/testing/local-https-setup.md

Installs the Caddy web server using the Homebrew package manager.

```bash
brew install caddy
```

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

### Install Application Dependencies

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/installation-guide.md

Installs project dependencies using Bun. Ensure you are in the application directory.

```bash
sudo -u rox bash << 'EOF'
cd /opt/rox/app
bun install
EOF
```

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

### Install Node.js LTS using Volta

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/installation-guide.md

Installs Volta for the 'rox' user and then installs the latest Long-Term Support (LTS) version of Node.js. Includes verification.

```bash
# Install Volta for the rox user
sudo -u rox bash -c 'curl https://get.volta.sh | bash'

# Install Node.js LTS
sudo -u rox /opt/rox/.volta/bin/volta install node@lts

# Verify node installation
sudo -u rox /opt/rox/.volta/bin/node --version
```

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

### Install mkcert on Linux

Source: https://github.com/love-rox/rox/blob/main/docker/certs/README.md

Installs mkcert on Linux by downloading the binary and moving it to the system's PATH. Requires libnss3-tools.

```bash
sudo apt install libnss3-tools
curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
chmod +x mkcert-v*-linux-amd64
sudo mv mkcert-v*-linux-amd64 /usr/local/bin/mkcert
```

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

### Install Docker on Ubuntu/Debian

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Install Docker using the official convenience script on Ubuntu/Debian systems.

```bash
curl -fsSL https://get.docker.com | sh
```

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

### Install Bun

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Install Bun, a JavaScript runtime, package manager, and test runner. Ensure you have Bun v1.0+ installed.

```bash
curl -fsSL https://bun.sh/install | bash
```

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

### Production Environment Configuration with S3 Storage

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/environment-variables.md

Example INI configuration for a production setup using S3 for storage. Requires S3 credentials and bucket details.

```ini
NODE_ENV=production
ROX_URL=https://rox.example.com
ROX_DOMAIN=rox.example.com
POSTGRES_PASSWORD=your-secure-password
ACME_EMAIL=admin@example.com
ENABLE_REGISTRATION=false
SESSION_EXPIRY_DAYS=30
LOG_LEVEL=info

STORAGE_TYPE=s3
S3_ENDPOINT=https://your-account.r2.cloudflarestorage.com
S3_BUCKET_NAME=rox-media
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_REGION=auto
S3_PUBLIC_URL=https://cdn.your-domain.com
```

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

### Display Installation Details

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/vps-docker.md

Echo key Rox installation details to the console. This is useful for quickly reviewing essential configuration parameters like domain, database password, and admin email.

```bash
echo "=== ROX INSTALLATION DETAILS ==="
echo "Domain: ${ROX_DOMAIN}"
echo "Database Password: ${ROX_DB_PASSWORD}"
echo "Admin Email: ${ROX_ADMIN_EMAIL}"
echo "================================"
```

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

### Build and Run Backend in Production Mode

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Build the backend application for production and then start the production server.

```bash
# Build backend
cd packages/backend
bun run build

# Start production server
NODE_ENV=production bun run start
```

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

### Production Environment Configuration with OAuth Providers

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/environment-variables.md

Example INI configuration for a production setup enabling registration and integrating with GitHub and Discord OAuth providers. Requires client IDs, secrets, and redirect URIs.

```ini
NODE_ENV=production
ROX_URL=https://rox.example.com
ROX_DOMAIN=rox.example.com
POSTGRES_PASSWORD=your-secure-password
ACME_EMAIL=admin@example.com
ENABLE_REGISTRATION=true

# GitHub OAuth
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
GITHUB_REDIRECT_URI=https://rox.example.com/api/auth/oauth/github/callback

# Discord OAuth
DISCORD_CLIENT_ID=your-discord-client-id
DISCORD_CLIENT_SECRET=your-discord-client-secret
DISCORD_REDIRECT_URI=https://rox.example.com/api/auth/oauth/discord/callback
```

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

### GoToSocial Configuration Example

Source: https://github.com/love-rox/rox/blob/main/docs/testing/mastodon-local-setup.md

Example configuration for GoToSocial, including host, database, and media storage settings. SQLite is used for simplicity.

```yaml
# Basic settings
host: "gotosocial.local"
account-domain: "gotosocial.local"
protocol: "https"
bind-address: "0.0.0.0"
port: 8080

# Database (SQLite for simplicity)
db-type: "sqlite"
db-address: "./gotosocial.db"

# Media storage
storage-local-base-path: "./storage"

# Accounts
accounts-registration-open: true
accounts-approval-required: false
```

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

### Enable and Start Rox Service

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/installation-guide.md

Reloads the systemd daemon, enables the Rox service to start on boot, and then starts the service. It also reloads Nginx to apply any configuration changes.

```bash
sudo systemctl daemon-reload
sudo systemctl enable rox
sudo systemctl start rox
sudo systemctl reload nginx
```

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

### Start Caddy Server

Source: https://github.com/love-rox/rox/blob/main/docs/testing/local-https-setup.md

Command to start the Caddy web server with a specific configuration file in a dedicated terminal.

```bash
cd ~/rox-testing
caddy run --config Caddyfile
```

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

### Build and Start Mastodon Services

Source: https://github.com/love-rox/rox/blob/main/docs/testing/mastodon-local-setup.md

Build the Docker images for Mastodon, set up the database with migrations and seeds, and then start all services in detached mode. Finally, check the status of the running services.

```bash
# Build images (takes 10-20 minutes)
docker-compose build

# Setup database
docker-compose run --rm web rails db:migrate
docker-compose run --rm web rails db:seed

# Start all services
docker-compose up -d

# Check status
docker-compose ps
```

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

### Initialize Misskey Database

Source: https://github.com/love-rox/rox/blob/main/docs/testing/local-https-setup.md

Starts the database and Redis services, waits for the database to be ready, and then initializes the Misskey database.

```bash
# Start database and redis first
docker-compose up -d db redis

# Wait for database to be ready
sleep 10

# Initialize Misskey database
docker-compose run --rm web pnpm run init
```

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

### Install Docker on macOS

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Install Docker desktop for macOS using Homebrew.

```bash
brew install --cask docker
```

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

### Start and Enable Dragonfly Service

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/installation-guide.md

Enables Dragonfly to start on boot and starts the service. Includes verification of the service status.

```bash
sudo systemctl enable dragonfly
sudo systemctl start dragonfly

# Verify
sudo systemctl status dragonfly
```

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

### Install Docker on Ubuntu/Debian

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/vps-docker.md

Installs Docker and Docker Compose on Ubuntu/Debian systems. Adds the current user to the docker group for easier management. Verifies the installation.

```bash
# Update system 
sudo apt update && sudo apt upgrade -y 

# Install Docker 
curl -fsSL https://get.docker.com | sh 

# Add your user to docker group 
sudo usermod -aG docker $USER 
newgrp docker 

# Verify installation 
docker --version 
docker compose version
```

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

### Install Bun Runtime

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/bare-metal.md

Installs the Bun JavaScript runtime for the current user and adds it to the system's PATH. Includes verification step.

```bash
# Install Bun for your current user
curl -fsSL https://bun.sh/install | bash

# Add to PATH (or restart shell)
source ~/.bashrc

# Verify installation
bun --version
```

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

### Generate Project Documentation

Source: https://github.com/love-rox/rox/blob/main/CONTRIBUTING.md

Install TypeDoc and generate API documentation for the project.

```bash
# Install TypeDoc
bun add -d typedoc

# Generate documentation
bunx typedoc --out docs/api packages/backend/src
```

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

### Release Notes Generation Examples

Source: https://github.com/love-rox/rox/blob/main/CONTRIBUTING.md

Examples demonstrating correct commit message formatting for automatic categorization in release notes, including type prefixes and scopes.

```bash
# Good - will appear in "🚀 New Features"
feat(auth): add OAuth2 login support
```

```bash
# Good - will appear in "🐛 Bug Fixes"
fix(timeline): resolve infinite scroll issue on mobile
```

```bash
# Good - will appear in "⚡ Performance"
perf(db): optimize user lookup queries
```

```bash
# Bad - will appear in "📝 Other Changes" (missing type prefix)
added new feature for user profiles
```

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

### Install Required System Packages

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/installation-guide.md

Installs essential packages including curl, git, Nginx, Certbot, PostgreSQL, and unzip.

```bash
sudo apt install -y \
    curl \
    git \
    nginx \
    certbot \
    python3-certbot-nginx \
    postgresql \
    postgresql-contrib \
    unzip
```

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

### Verify Bun Installation

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Verify that Bun is installed correctly by checking its version. Expected output is 1.x.x.

```bash
bun --version
# Should output: 1.x.x
```

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

### Install Git on Ubuntu/Debian

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Install Git version control using apt on Ubuntu/Debian systems.

```bash
sudo apt install git
```

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

### Start Misskey Instance

Source: https://github.com/love-rox/rox/blob/main/docs/testing/misskey-local-setup.md

Starts all services defined in the docker-compose.yml file for the Misskey instance in detached mode.

```bash
cd /tmp/misskey
docker-compose up -d
```

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

### Start Caddy Reverse Proxy

Source: https://github.com/love-rox/rox/blob/main/docs/testing/local-https-setup.md

Starts the Caddy reverse proxy. Use 'caddy run' to see logs in the foreground or 'caddy start' to run in the background. Ensure you are in the correct directory.

```bash
cd ~/rox-testing

# Start Caddy in foreground to see logs
caddy run --config Caddyfile

# Or start in background
caddy start --config Caddyfile
```

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

### Cross-Database Migration Example

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Perform a cross-database migration by exporting from the source database, setting up the target database with migrations, and then importing the data.

```bash
# 1. Export from PostgreSQL
DB_TYPE=postgres DATABASE_URL="postgresql://..." bun run db:export

# 2. Create SQLite database and run migrations
DB_TYPE=sqlite DATABASE_URL="sqlite://./rox.db" bun run db:migrate

# 3. Import to SQLite
DB_TYPE=sqlite DATABASE_URL="sqlite://./rox.db" bun run db:import backups/export-xxxx.json
```

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

### GoToSocial Configuration Example

Source: https://github.com/love-rox/rox/blob/main/docs/testing/federation-test-results.md

Example configuration for GoToSocial, focusing on instance federation mode and HTTP client settings to allow specific IP ranges for local testing.

```yaml
host: "gts.local"
protocol: "https"
instance-federation-mode: "blocklist"

# Allow Docker's internal IP ranges for local testing
http-client:
  timeout: "30s"
  allow-ips:
    - "0.250.250.0/24"  # Docker Desktop host-gateway
    - "127.0.0.0/8"
    - "192.168.0.0/16"
    - "10.0.0.0/8"
    - "172.16.0.0/12"
```

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

### Start Mastodon Services

Source: https://github.com/love-rox/rox/blob/main/docs/testing/mastodon-local-setup.md

Navigate to the Mastodon directory and use this command to start all services in detached mode.

```bash
cd /tmp/mastodon
docker-compose up -d
```

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

### Display Rox Installation Details

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/bare-metal.md

Prints essential Rox installation variables to the console. Ensure these values are saved securely for future maintenance.

```bash
echo "=== ROX INSTALLATION DETAILS ==="
 echo "Domain: ${ROX_DOMAIN}"
 echo "Database Password: ${ROX_DB_PASSWORD}"
 echo "Admin Email: ${ROX_ADMIN_EMAIL}"
 echo "================================
```

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

### Configure PostgreSQL Database

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/installation-guide.md

Starts and enables the PostgreSQL service, then creates a database user 'rox' and a database 'rox' with specified password.

```bash
# Start PostgreSQL
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database and user
sudo -u postgres psql << EOF
CREATE USER rox WITH PASSWORD '${ROX_DB_PASSWORD}';
CREATE DATABASE rox OWNER rox;
GRANT ALL PRIVILEGES ON DATABASE rox TO rox;
\q
EOF
```

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

### Install TSDoc ESLint Plugin

Source: https://github.com/love-rox/rox/blob/main/CONTRIBUTING.md

Optional step to install the TSDoc ESLint plugin for checking documentation.

```bash
# Use TSDoc ESLint plugin (optional)
bun add -d eslint-plugin-tsdoc
```

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

### Clone and Install Rox Dependencies

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/bare-metal.md

Clones the Rox repository into the /opt directory, sets ownership, and installs project dependencies using Bun.

```bash
# Clone repository
cd /opt
sudo git clone https://github.com/your-org/rox.git
sudo chown -R $USER:$USER rox
cd rox

# Install dependencies
bun install

# Build (if needed)
bun run build
```

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

### Install mkcert on Windows

Source: https://github.com/love-rox/rox/blob/main/docker/certs/README.md

Installs mkcert on Windows using Chocolatey. This is a prerequisite for generating local SSL certificates.

```powershell
choco install mkcert
```

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

### Verify Misskey Installation

Source: https://github.com/love-rox/rox/blob/main/docs/testing/misskey-local-setup.md

Perform checks on the installed Misskey instance, including WebFinger, NodeInfo, and ActivityPub actor endpoints.

```bash
# Check WebFinger
curl "https://xyz789.ngrok.io/.well-known/webfinger?resource=acct:alice@xyz789.ngrok.io"

# Check NodeInfo
curl https://xyz789.ngrok.io/nodeinfo/2.1

# Check Actor
curl -H "Accept: application/activity+json" https://xyz789.ngrok.io/users/alice
```

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

### Install mkcert on macOS

Source: https://github.com/love-rox/rox/blob/main/docker/certs/README.md

Installs mkcert using Homebrew on macOS. This is the first step for manual certificate generation.

```bash
brew install mkcert
```

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

### Install Required System Packages

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/bare-metal.md

Installs essential packages for building and running applications, including curl, git, and build tools.

```bash
sudo apt install -y curl git build-essential
```

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

### Start ngrok for Public Access

Source: https://github.com/love-rox/rox/blob/main/docs/testing/misskey-local-setup.md

Use ngrok to expose the local Misskey instance running on port 3000 to a public URL.

```bash
# In a new terminal
ngrok http 3000

# ngrok will output a URL like: https://xyz789.ngrok.io
# Copy this URL
```

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

### Install Bun Runtime

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/installation-guide.md

Installs the Bun JavaScript runtime and sources the bashrc to make it available in the current session. Includes verification.

```bash
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc

# Verify installation
bun --version
```

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

### Clean Up Misskey Setup

Source: https://github.com/love-rox/rox/blob/main/docs/testing/misskey-local-setup.md

Stops and removes all Misskey services and their associated volumes, then removes the Misskey repository directory.

```bash
# Stop and remove everything
docker-compose down -v

# Remove repository
cd ..
rm -rf misskey
```

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

### Check Claude Installation and Login

Source: https://github.com/love-rox/rox/blob/main/docs/development/devcontainer.md

Verify the installation of the Claude CLI, check its version, and re-authenticate if necessary. Also, confirm the API key is set.

```bash
# Check installation
which claude
claude --version

# Re-login
claude login

# Check API key
echo $ANTHROPIC_API_KEY
```

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

### Start and Monitor Misskey Services

Source: https://github.com/love-rox/rox/blob/main/docs/testing/local-https-setup.md

Starts all Misskey services in detached mode, checks their status, and follows the logs for the web service.

```bash
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f web
```

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

### Plugin Manifest Example (plugin.json)

Source: https://github.com/love-rox/rox/blob/main/plugins/README.md

Defines the metadata for a Rox plugin, including its ID, name, version, and required Rox version.

```json
{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "Plugin description",
  "author": "Your Name",
  "minRoxVersion": "2025.12.0",
  "permissions": ["notes:read", "notes:write"]
}
```

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

### Clone and Set Up Firefish (Misskey Lightweight Fork)

Source: https://github.com/love-rox/rox/blob/main/docs/testing/misskey-local-setup.md

Steps to clone the Firefish repository, configure it using Docker, and start the service. This is an alternative for users seeking lighter resource usage.

```bash
cd /tmp
git clone https://github.com/firefish-dev/firefish.git
cd firefish

# Follow similar steps to Misskey
cp .config/docker_example.yml .config/default.yml
docker-compose build
docker-compose run --rm web pnpm run init
docker-compose up -d
```

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

### Unit Test Example

Source: https://github.com/love-rox/rox/blob/main/docs/development/testing.md

Example of a unit test for NoteService. It includes setup with mock repositories and tests for creating a note and handling empty text.

```typescript
import { describe, it, expect, beforeEach, mock } from 'bun:test';
import { NoteService } from '../../services/NoteService';

describe('NoteService', () => {
  let noteService: NoteService;
  let mockNoteRepository: any;
  let mockUserRepository: any;

  beforeEach(() => {
    // Create mock repositories
    mockNoteRepository = {
      create: mock(() => Promise.resolve({ id: 'note-123' })),
      findById: mock(() => Promise.resolve(null)),
    };
    mockUserRepository = {
      findById: mock(() => Promise.resolve({ id: 'user-123', username: 'test' })),
    };

    noteService = new NoteService(mockNoteRepository, mockUserRepository);
  });

  describe('createNote', () => {
    it('should create a note with valid input', async () => {
      const result = await noteService.create({
        text: 'Hello, world!',
        userId: 'user-123',
        visibility: 'public',
      });

      expect(result).toBeDefined();
      expect(result.id).toBe('note-123');
      expect(mockNoteRepository.create).toHaveBeenCalledTimes(1);
    });

    it('should throw error for empty text', async () => {
      await expect(
        noteService.create({
          text: '',
          userId: 'user-123',
          visibility: 'public',
        })
      ).rejects.toThrow();
    });
  });
});
```

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

### Integration Test Example

Source: https://github.com/love-rox/rox/blob/main/docs/development/testing.md

Example of an integration test for API endpoints. It sets up the application and tests the 'GET /api/notes/local-timeline' endpoint for returning public notes and respecting the limit parameter.

```typescript
import { describe, it, expect, beforeAll, afterAll } from 'bun:test';
import { createApp } from '../../app';

describe('API Endpoints', () => {
  let app: ReturnType<typeof createApp>;

  beforeAll(async () => {
    app = createApp();
  });

  describe('GET /api/notes/local-timeline', () => {
    it('should return public notes', async () => {
      const response = await app.request('/api/notes/local-timeline', {
        method: 'GET',
      });

      expect(response.status).toBe(200);
      const data = await response.json();
      expect(Array.isArray(data)).toBe(true);
    });

    it('should respect limit parameter', async () => {
      const response = await app.request('/api/notes/local-timeline?limit=5', {
        method: 'GET',
      });

      expect(response.status).toBe(200);
      const data = await response.json();
      expect(data.length).toBeLessThanOrEqual(5);
    });
  });
});
```

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

### Run Full Stack in Development Mode

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Start both the backend and frontend development servers concurrently in separate terminals.

```bash
# Terminal 1 - Backend
cd packages/backend && bun run dev

# Terminal 2 - Frontend
cd packages/frontend && bun run dev
```

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

### Run Backend in Development Mode

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Start the backend server in development mode. Configure database connection, local storage, port, and other environment variables.

```bash
cd packages/backend
DB_TYPE=postgres \
DATABASE_URL="postgresql://rox:rox_dev_password@localhost:5432/rox" \
STORAGE_TYPE=local \
LOCAL_STORAGE_PATH=./uploads \
PORT=3000 \
NODE_ENV=development \
URL=http://localhost:3000 \
ENABLE_REGISTRATION=true \
SESSION_EXPIRY_DAYS=30 \
bun run dev
```

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

### Quick Start Deployment with Docker Compose

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/vps-docker.md

A streamlined process to clone the Rox repository, configure the production environment file, and deploy using Docker Compose. Includes steps for verification.

```bash
# 1. Clone the repository 
git clone https://github.com/your-org/rox.git 
cd rox 

# 2. Configure environment (using variables) 
cat > docker/.env.production << EOF 
ROX_DOMAIN=${ROX_DOMAIN} 
ROX_URL=https://${ROX_DOMAIN} 
POSTGRES_PASSWORD=${ROX_DB_PASSWORD} 
ENABLE_REGISTRATION=true 
EOF 

# 3. Deploy 
docker compose -f docker/compose.yml up -d 

# 4. Verify 
docker compose -f docker/compose.yml ps 
curl http://localhost/health
```

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

### Configure Environment Variables

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/vps-docker.md

Set essential environment variables for your Rox installation, such as domain name, database password, and admin email. These variables are used throughout the setup process.

```bash
# ============================================ 
# SET THESE VALUES FOR YOUR INSTALLATION 
# ============================================ 

# Your domain name (without https://) 
export ROX_DOMAIN="rox.example.com" 

# Generate a secure database password (or set your own) 
export ROX_DB_PASSWORD=$(openssl rand -base64 32) 

# Your email address (for notifications) 
export ROX_ADMIN_EMAIL="admin@example.com" 

# ============================================ 
# VERIFY YOUR SETTINGS 
# ============================================ 
echo "Domain: $ROX_DOMAIN" 
echo "Database Password: $ROX_DB_PASSWORD" 
echo "Admin Email: $ROX_ADMIN_EMAIL"
```

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

### Production Environment Configuration with External PostgreSQL

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/environment-variables.md

Example INI configuration for a production setup using an external PostgreSQL database and Dragonfly for caching. Assumes S3 configuration is present.

```ini
NODE_ENV=production
ROX_URL=https://rox.example.com
DATABASE_URL=postgresql://user:password@db.provider.com:5432/rox?sslmode=require
DRAGONFLY_URL=redis://redis.provider.com:6379
STORAGE_TYPE=s3
# ... S3 config ...
```

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

### Install Dragonfly Natively

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/installation-guide.md

Installs Dragonfly using the official APT repository. Ensure you have curl and gpg installed.

```bash
# Add Dragonfly repository
curl -fsSL https://www.dragonflydb.io/dragonfly-apt.gpg | sudo gpg --dearmor -o /usr/share/keyrings/dragonfly-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/dragonfly-archive-keyring.gpg] https://apt.dragonflydb.io $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/dragonfly.list

# Install
sudo apt update
sudo apt install -y dragonfly
```

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

### Install Certbot and Obtain SSL Certificate

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/nginx-configuration.md

Installs Certbot and obtains an SSL certificate for a domain using Nginx. Ensure Certbot and the Nginx plugin are installed.

```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d rox.example.com
```

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

### Initialize GoToSocial Configuration

Source: https://github.com/love-rox/rox/blob/main/docs/testing/mastodon-local-setup.md

Generate a default configuration file for GoToSocial.

```bash
./gotosocial --config-path ./config.yaml init
```

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

### Install Git on macOS

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Install Git version control using Homebrew on macOS.

```bash
brew install git
```

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

### Inline Comment Examples

Source: https://github.com/love-rox/rox/blob/main/CONTRIBUTING.md

Examples of inline comments in both Japanese and English for code clarity.

```typescript
// ユーザーごとのディレクトリに保存
const relativePath = join(metadata.userId, filename);
```

```typescript
// Save to user-specific directory
const relativePath = join(metadata.userId, filename);
```

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

### Set Rox Installation Configuration Variables

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/installation-guide.md

Set essential environment variables for your Rox installation, including domain, database password, and admin email. These variables are crucial for the installation process and should be set once at the beginning of your session.

```bash
# ============================================
# SET THESE VALUES FOR YOUR INSTALLATION
# ============================================

# Your domain name (without https://)
export ROX_DOMAIN="rox.example.com"

# Generate a secure database password (or set your own)
export ROX_DB_PASSWORD=$(openssl rand -base64 32)

# Your email address (for SSL certificate notifications)
export ROX_ADMIN_EMAIL="admin@example.com"

# ============================================
# VERIFY YOUR SETTINGS
# ============================================
echo "Domain: $ROX_DOMAIN"
echo "Database Password: $ROX_DB_PASSWORD"
echo "Admin Email: $ROX_ADMIN_EMAIL"
```

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

### Plugin Entry Point Example (index.js)

Source: https://github.com/love-rox/rox/blob/main/plugins/README.md

The main JavaScript file for a Rox plugin, exporting an object with lifecycle methods like onLoad and routes.

```javascript
export default {
  id: "my-plugin",
  name: "My Plugin",
  version: "1.0.0",

  async onLoad(context) {
    // Called when plugin is loaded
    context.logger.info("Plugin loaded!");

    // Subscribe to events
    context.events.on("note:afterCreate", (payload) => {
      context.logger.info(`Note created: ${payload.note.id}`);
    }, "my-plugin");
  },

  async onUnload() {
    // Called when plugin is unloaded
  },

  // Optional: Custom API routes at /api/x/my-plugin/
  routes(app) {
    app.get("/", (c) => c.json({ hello: "world" }));
  },
};

```

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

### Initiate Follow Activity (Rox to Misskey)

Source: https://github.com/love-rox/rox/blob/main/docs/testing/federation-test-results.md

Tests the process of Rox initiating a follow activity towards a Misskey user. This involves creating a local follow relationship and verifying that the corresponding ActivityPub activity is correctly signed, delivered to Misskey's inbox, and logged.

```bash
curl -X POST 'https://rox.local/api/following/create' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"userId": "mienzgvb5a17zbwz"}'
```

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

### Rox Health Response Example

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/installation-guide.md

An example of the expected JSON response from the Rox health endpoint.

```json
{
  "status": "ok",
  "timestamp": "2025-11-28T...",
  "version": "0.1.0"
}
```

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

### Run Development Services and Tests Locally

Source: https://github.com/love-rox/rox/blob/main/docs/development/testing.md

Start necessary database services using Docker Compose and then run tests with the Bun test runner. Ensure PostgreSQL is ready before proceeding.

```bash
docker compose -f docker/compose.dev.yml up -d

until pg_isready -h localhost -U rox -d rox; do sleep 1; done

bun test
```

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

### Build Application Backend and Frontend

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/installation-guide.md

Builds the backend and frontend components of the Rox application using Bun.

```bash
sudo -u rox bash << 'EOF'
cd /opt/rox/app

# Build backend
cd packages/backend
bun run build

# Build frontend
cd ../frontend
bun run build
EOF
```

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

### Check Service Logs and Environment

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/installation-guide.md

Diagnose service startup failures by checking backend and frontend logs using journalctl. Verify the application's environment configuration and test the database connection.

```bash
# Check logs
sudo journalctl -u rox-backend -n 50 --no-pager
sudo journalctl -u rox-frontend -n 50 --no-pager

# Verify environment
sudo -u rox cat /opt/rox/app/.env

# Test database connection
PGPASSWORD="${ROX_DB_PASSWORD}" psql -U rox -h localhost -d rox -c "SELECT 1;"
```

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

### Set Up Pre-commit Hook

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Create and make executable a pre-commit hook script that runs type checks and tests before each commit. Ensure you are in the project root.

```bash
#!/bin/bash
set -e

echo "Running type check..."
cd packages/backend && bunx tsc --noEmit

echo "Running tests..."
bun test

echo "All checks passed!"
```

```bash
chmod +x .git/hooks/pre-commit
```

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

### Start Misskey with Docker Compose

Source: https://github.com/love-rox/rox/blob/main/docs/testing/local-https-setup.md

Command to start the Misskey service using Docker Compose in a dedicated terminal.

```bash
cd /tmp/misskey
docker-compose up
```

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

### Manual Integration and E2E Test Execution

Source: https://github.com/love-rox/rox/blob/main/docs/development/testing.md

Steps to manually start the server and run integration or E2E tests in separate terminal sessions.

```bash
# 1. Start the server
bun run dev

# 2. In another terminal, run integration tests
bun test src/tests/integration/

# 3. Run E2E tests
bun test src/tests/e2e/
```

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

### Local Misskey Instance Setup with Docker

Source: https://github.com/love-rox/rox/blob/main/docs/testing/federation-test-plan.md

Clone the Misskey repository and use Docker Compose to set up a local Misskey instance for testing federation. Ensure the instance is publicly accessible with SSL.

```bash
git clone https://github.com/misskey-dev/misskey
cd misskey
docker-compose up -d
```

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

### Structured Log Format Example

Source: https://github.com/love-rox/rox/blob/main/docs/implementation/phase-6-production-readiness.md

Example of a structured log entry, including request ID, activity type, and target.

```json
{
  "level": "info",
  "time": "2025-11-26T12:00:00Z",
  "requestId": "abc123",
  "message": "Activity delivered",
  "activityType": "Create",
  "targetInbox": "https://example.com/inbox",
  "duration": 234
}
```

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

### Run All Tests

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Navigate to the backend package directory and execute all tests using the bun test command.

```bash
cd packages/backend
bun test
```

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

### Conventional Commits Examples

Source: https://github.com/love-rox/rox/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification, including type, scope, and subject.

```bash
feat: add user registration endpoint
```

```bash
fix: resolve session expiration bug
```

```bash
docs: update API documentation
```

```bash
refactor: simplify password hashing logic
```

```bash
test: add authentication service tests
```

```bash
chore: update dependencies
```

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

### Run ActivityPub Test Scripts

Source: https://github.com/love-rox/rox/blob/main/docs/activitypub-test-results.md

Navigate to the backend package directory and execute the inbox and follow relationship tests using bun.

```bash
cd packages/backend
bun run test-inbox-real.ts
bun run check-follow.ts
```

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

### Install Dragonfly (Optional Cache/Queue)

Source: https://github.com/love-rox/rox/blob/main/docs/deployment/bare-metal.md

Downloads, installs, and configures Dragonfly as a systemd service for Redis-compatible caching and job queue functionality.

```bash
# Download Dragonfly
curl -L https://github.com/dragonflydb/dragonfly/releases/latest/download/dragonfly-x86_64.tar.gz | tar xz

# Move to system location
sudo mv dragonfly /usr/local/bin/

# Create data directory
sudo mkdir -p /var/lib/dragonfly
sudo chown $USER:$USER /var/lib/dragonfly

# Create systemd service
sudo tee /etc/systemd/system/dragonfly.service > /dev/null <<EOF
[Unit]
Description=Dragonfly In-Memory Database
After=network.target

[Service]
Type=simple
User=$USER
ExecStart=/usr/local/bin/dragonfly --dir /var/lib/dragonfly --maxmemory 256mb
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# Start Dragonfly
sudo systemctl daemon-reload
sudo systemctl enable dragonfly
sudo systemctl start dragonfly

# Verify
redis-cli ping
```

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

### Verify Database Schema

Source: https://github.com/love-rox/rox/blob/main/docs/development.md

Connect to the PostgreSQL database and list all tables to verify that the migrations have created the expected schema.

```bash
# Connect to database
psql postgresql://rox:rox_dev_password@localhost:5432/rox

# List tables
\dt

# Expected tables:
# users, sessions, notes, reactions, follows, drive_files
```

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

### Dependency Injection with Hono Context

Source: https://github.com/love-rox/rox/blob/main/docs/implementation/overview.md

Demonstrates how to set up dependency injection for repositories using Hono's context. The repository implementation is chosen based on environment variables during application startup. Controllers then depend on the abstract interface.

```typescript
const noteRepository = createNoteRepository(process.env.DB_TYPE);
app.use('*', async (c, next) => {
  c.set('noteRepository', noteRepository);
  await next();
});

app.get('/api/notes', async (c) => {
  const repo = c.get('noteRepository'); // INoteRepository
  const notes = await repo.getTimeline();
  return c.json(notes);
});
```