環境構築の概要

HoppscotchはブラウザベースのAPI開発ツールとして広く利用されていますが、チーム内でのデータ共有やセキュリティ要件を満たすためには自前のサーバー環境への導入が望ましいです。本稿では、Docker Composeを用いてデータベース・アプリケーション・リバースプロキシを統合し、独自ドメインまたはローカルIPに対してHTTPSを有効化した運用環境を構築する手順を解説します。認証方式はメールアドレスベースに固定し、設定の簡略化を図ります。

コンテナ連携と設定ファイル

アプリケーション環境変数 (hoppscotch.env)

公式のデフォルト構成を基に、認証プロバイダをメールのみへ限定し、HTTPS通信に必要なリダイレクト先および許可オリジンをプレースホルダー化しています。SMTP関連の設定は実行時に動的に書き換える形式としています。

# ── Backend Configuration ──
# Database Connection
DATABASE_URL=postgresql://db_admin:secure_db_pass@postgres:5432/api_client_db

# Authentication Tokens
JWT_SECRET=change_this_to_a_strong_random_string
TOKEN_SALT_COMPLEXITY=32
MAGIC_LINK_TOKEN_VALIDITY=30
REFRESH_TOKEN_VALIDITY=604800000
ACCESS_TOKEN_VALIDITY=604800000
SESSION_SECRET=generate_secure_session_secret_here

# Domain & Origin Configuration
REDIRECT_URL=https://TARGET_HOST
WHITELISTED_ORIGINS=https://TARGET_HOST,https://TARGET_HOST/admin,https://TARGET_HOST/backend
VITE_ALLOWED_AUTH_PROVIDERS=EMAIL

# Third-party Auth (Disabled)
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""
MICROSOFT_CLIENT_ID=""
MICROSOFT_CLIENT_SECRET=""

# SMTP Mailer
MAILER_SMTP_URL=MAIL_SMTP_ENDPOINT
MAILER_ADDRESS_FROM=MAIL_SENDER_ADDR

# Rate Limiting
RATE_LIMIT_TTL=60
RATE_LIMIT_MAX=120

# ── Frontend Configuration ──
VITE_BASE_URL=https://TARGET_HOST
VITE_SHORTCODE_BASE_URL=https://TARGET_HOST
VITE_ADMIN_URL=https://TARGET_HOST/admin

VITE_BACKEND_GQL_URL=https://TARGET_HOST/backend/graphql
VITE_BACKEND_WS_URL=wss://TARGET_HOST/backend/graphql
VITE_BACKEND_API_URL=https://TARGET_HOST/backend/v1

VITE_APP_TOS_LINK=https://docs.hoppscotch.io/support/terms
VITE_APP_PRIVACY_POLICY_LINK=https://docs.hoppscotch.io/support/privacy
ENABLE_SUBPATH_BASED_ACCESS=true

リバースプロキシ設定 (nginx.conf)

WebSocket通信のアップグレードとHTTPS終端を担います。HSTSヘッダーを追加し、各パス（ルート、管理画面、バックエンドAPI）へのプロキシルールを明示的に定義しています。

map $http_upgrade $ws_connection {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl http2;
    server_name TARGET_HOST;

    ssl_certificate /etc/nginx/certs/server.crt;
    ssl_certificate_key /etc/nginx/certs/server.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    proxy_http_version 1.1;

    location / {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $ws_connection;
        proxy_pass http://hoppscotch_app:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location /admin {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $ws_connection;
        proxy_pass http://hoppscotch_app:3000/admin;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location /backend {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $ws_connection;
        proxy_pass http://hoppscotch_app:3000/backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location /proxy {
        proxy_pass http://api_proxy_service:9159;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

コンテナオーケストレーション (docker-compose.yml)

データベースマイグレーション、アプリケーション本体、プロキシ、リバースプロキシを分離し、依存関係を明示的に定義しています。ボリュームのマウント先とネットワーク名をカスタマイズしています。

services:
  db_service:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: api_client_db
      POSTGRES_USER: db_admin
      POSTGRES_PASSWORD: secure_db_pass
    volumes:
      - ./storage/db_data:/var/lib/postgresql/data
    networks:
      - hoppscotch_network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U db_admin"]
      interval: 10s
      timeout: 5s
      retries: 5

  schema_migration:
    image: hoppscotch/hoppscotch:latest
    env_file:
      - ./config/runtime.env
    entrypoint: sh
    depends_on:
      db_service:
        condition: service_healthy
    networks:
      - hoppscotch_network
    restart: "no"
    command: -c "npx prisma migrate deploy"

  hoppscotch_app:
    image: hoppscotch/hoppscotch:latest
    env_file:
      - ./config/runtime.env
    depends_on:
      schema_migration:
        condition: service_completed_successfully
    networks:
      - hoppscotch_network
    restart: unless-stopped

  api_proxy_service:
    image: hoppscotch/proxyscotch:latest
    networks:
      - hoppscotch_network
    restart: unless-stopped
    depends_on:
      - hoppscotch_app

  reverse_proxy:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./config/nginx/nginx.conf:/etc/nginx/conf.d/default.conf
      - ./storage/nginx/certs:/etc/nginx/certs
    depends_on:
      - hoppscotch_app
    networks:
      - hoppscotch_network
    restart: unless-stopped

networks:
  hoppscotch_network:
    driver: bridge
    name: hoppscotch_isolated_net

デプロイ自動化スクリプト

環境構築と起動 (deploy.sh)

プレースホルダー置換、自己署名証明書の自動生成、Docker Composeの起動を連動させます。引数としてアクセス先アドレス、SMTP接続文字列、送信元メールアドレスを渡します。

#!/usr/bin/env bash
set -euo pipefail

if [ "$#" -ne 3 ]; then
  echo "Usage: $0 <host_address> <smtp_connection_string> <sender_email>"
  exit 1
fi

HOST_ADDR="$1"
SMTP_CONN="$2"
MAIL_SENDER="$3"

# ディレクトリ構造の確保
mkdir -p storage/nginx/certs storage/db_data config/nginx config/runtime

# Nginx設定のテンプレート展開
sed "s/TARGET_HOST/${HOST_ADDR}/g" templates/nginx.conf > config/nginx/nginx.conf

# 自己署名証明書の発行
./issue_cert.sh "${HOST_ADDR}" "storage/nginx/certs"

# 環境変数ファイルの生成
cat templates/hoppscotch.env | \
  sed "s/TARGET_HOST/${HOST_ADDR}/g" | \
  sed "s|MAIL_SMTP_ENDPOINT|${SMTP_CONN}|g" | \
  sed "s/MAIL_SENDER_ADDR/${MAIL_SENDER}/g" > config/runtime.env

# コンテナの起動
docker compose up -d --build

環境クリーンアップ (cleanup.sh)

コンテナの停止と関連ボリュームの削除を行います。データ保持が必要な場合は、`storage` ディレクトリの削除処理を手動でコメントアウトしてください。

#!/usr/bin/env bash
set -euo pipefail

echo "Stopping and removing containers..."
docker compose down

if [ -d "storage" ]; then
  echo "Removing persistent data volumes..."
  rm -rf storage
fi

echo "Cleanup completed."

証明書発行ユーティリティ (issue_cert.sh)

OpenSSLを使用してCNとSANに指定されたIPアドレスが有効な自己署名証明書を作成します。本番環境ではLet's Encryptなどの認証局签发された鍵ペアへ差し替えてください。

#!/usr/bin/env bash
set -euo pipefail

if [ "$#" -ne 2 ]; then
  echo "Usage: $0 <target_ip> <output_directory>"
  exit 1
fi

TARGET_IP="$1"
OUTPUT_DIR="$2"

mkdir -p "${OUTPUT_DIR}"

echo "Generating private key..."
openssl genrsa -out "${OUTPUT_DIR}/server.key" 2048

echo "Creating CSR..."
openssl req -new -key "${OUTPUT_DIR}/server.key" -out "${OUTPUT_DIR}/server.csr" -subj "/CN=${TARGET_IP}"

echo "Signing certificate with SAN extension..."
openssl x509 -req -days 365 \
  -in "${OUTPUT_DIR}/server.csr" \
  -signkey "${OUTPUT_DIR}/server.key" \
  -out "${OUTPUT_DIR}/server.crt" \
  -extfile <(printf "subjectAltName=IP:${TARGET_IP}")

echo "Certificate generated at ${OUTPUT_DIR}"

ディレクトリ構成

project_root/
├── config/
│   ├── nginx/
│   │   └── nginx.conf          # 展開されたプロキシ設定
│   └── runtime.env             # 展開された環境変数
├── storage/
│   ├── db_data/                # PostgreSQLデータ領域
│   └── nginx/
│       └── certs/              # SSL鍵ペア保存先
├── templates/
│   ├── nginx.conf              # プロキシ設定テンプレート
│   └── hoppscotch.env          # アプリ設定テンプレート
├── docker-compose.yml
├── deploy.sh
├── cleanup.sh
└── issue_cert.sh

運用とデータ確認

スクリプト実行後、ブラウザで `https://<設定IP>` にアクセスするとAPIクライアント画面、`/admin` パスには管理ダッシュボードがそれぞれ表示されます。初期管理者アカウントはメール認証画面からマジックリンク経由で登録可能です。

データベースの状態を直接確認する必要がある場合は、ホスト側で以下のコマンドを実行し、PostgreSQLクライアントに接続します。

docker exec -it hoppscotch_isolated_net-db_service-1 psql -U db_admin -d api_client_db