インストール

ワンコマンドインストール（新規 Linux ホスト）

SSH したばかりの素の VM 向け。Docker が無ければ導入し、./shumoku に compose.yaml と .env を配置してサービスを起動します:

curl -fsSL https://raw.githubusercontent.com/konoe-akitoshi/shumoku/main/apps/server/scripts/install.sh | sh

本番では、バージョンを固定しポート 80 で公開するのが推奨です:

curl -fsSL https://raw.githubusercontent.com/konoe-akitoshi/shumoku/main/apps/server/scripts/install.sh \
  | SHUMOKU_VERSION=0.1.4 SHUMOKU_PORT=80 sh

環境変数で調整: SHUMOKU_VERSION（既定 latest）、SHUMOKU_PORT（既定 8080）、 DEMO_MODE（既定 false）、INSTALL_DIR（既定 ./shumoku）。パイプ前に中身を確認したい場合はスクリプト本体を参照してください: apps/server/scripts/install.sh。

イメージの検証（署名・SBOM）

公開イメージには GitHub Actions の OIDC を用いた Cosign キーレス署名が付き、 SBOM と SLSA provenance が OCI アテステーションとして添付されています（本機能導入以降に公開されたリリースが対象）。取得前に、正規の CI が作ったイメージか検証できます:

cosign verify \
  --certificate-identity-regexp '^https://github.com/konoe-akitoshi/shumoku/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/konoe-akitoshi/shumoku:latest

SBOM / provenance の確認:

# SBOM（含まれるパッケージ一覧）
cosign download sbom ghcr.io/konoe-akitoshi/shumoku:latest

# provenance（どのビルドで作られたか）
docker buildx imagetools inspect ghcr.io/konoe-akitoshi/shumoku:latest \
  --format '{{ json .Provenance }}'

イメージは linux/amd64 と linux/arm64 のマルチアーキで公開されるため、ARM の VPS や Apple Silicon でも同じタグがそのまま動きます。

Systemd（Linux）

インストール

git clone https://github.com/konoe-akitoshi/shumoku.git /opt/shumoku
cd /opt/shumoku/apps/server

make setup

sudo mkdir -p /var/lib/shumoku
sudo chown shumoku:shumoku /var/lib/shumoku

sudo cp scripts/shumoku.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable shumoku
sudo systemctl start shumoku

管理

sudo systemctl status shumoku      # ステータス確認
sudo journalctl -u shumoku -f      # ログ表示
sudo systemctl restart shumoku     # 再起動

アップデート

cd /opt/shumoku
git pull
cd apps/server
make setup
sudo systemctl restart shumoku

手動

インストール

git clone https://github.com/konoe-akitoshi/shumoku.git
cd shumoku/apps/server
make setup
make start

# カスタム設定で起動
DATA_DIR=/path/to/data PORT=8080 bun dist/index.js

アップデート

cd shumoku
git pull
cd apps/server
make setup
make start

リバースプロキシ（nginx）

server {
    listen 80;
    server_name shumoku.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

WebSocket（/ws）には上記の Upgrade / Connection ヘッダーが必要です。

環境変数

変数	説明	デフォルト
`PORT`	サーバーポート	`8080`
`HOST`	バインドアドレス	`0.0.0.0`
`DATA_DIR`	データディレクトリ（SQLite）	`/data`
`SHUMOKU_PORT`	外部ポート（Docker Compose）	`8080`
`DEMO_MODE`	空の DB にサンプルネットワークを読み込む	`false`

全データは /data 以下の SQLite DB（shumoku.db）に格納されています。ただし WAL モードで動作するため、直近の書き込みは shumoku.db-wal 側に残ります。どのタイミングで本体へ反映されるかは SQLite の自動チェックポイント任せで、停止しても強制されません。そのため shumoku.db 単体のコピーは不完全になり得ます （ほぼ空になることもあります）。バックアップは shumoku.db / shumoku.db-wal / shumoku.db-shm を揃えて取得するか、/data を丸ごとコピーしてください。

Docker — 一時停止して /data ボリュームを丸ごと固めるのが最も確実です:

# バックアップ
docker compose stop
docker run --rm -v shumoku-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/shumoku-backup.tgz -C /data .
docker compose start

# リストア
docker compose stop
docker run --rm -v shumoku-data:/data -v "$PWD":/backup alpine \
  sh -c 'rm -rf /data/* && tar xzf /backup/shumoku-backup.tgz -C /data'
docker compose start

Systemd — DB ファイルを 3 つまとめて（shumoku.db*）コピーします:

sudo systemctl stop shumoku
cp /var/lib/shumoku/shumoku.db* ./backup/
sudo systemctl start shumoku

# リストア
sudo systemctl stop shumoku
cp ./backup/shumoku.db* /var/lib/shumoku/
sudo systemctl start shumoku

スキーマ変更を含むアップデートの前には、必ずバックアップを取ってください。

本番での継続バックアップ（推奨）

上記の手動バックアップは「時々・手元に」取る最小構成です。本番では、SQLite を止めずにオフサイトへ継続複製する Litestream の併用を推奨します。WAL を購読して S3 / MinIO / Azure Blob などへ near-real-time にレプリケートし、任意時点への復元（point-in-time restore）ができます。生ファイルコピーではなく SQLite の仕組みを使うため、アプリを止めず・DB を壊さずに動きます。compose.yaml にサイドカーを 1 つ足すだけです:

services:
  # shumoku サービスはそのまま（同じ shumoku-data volume を共有します）
  litestream:
    image: litestream/litestream:0.5.9
    restart: unless-stopped
    depends_on: [shumoku]
    volumes:
      - shumoku-data:/data
      - ./litestream.yml:/etc/litestream.yml:ro
    command: replicate
    environment:
      - LITESTREAM_ACCESS_KEY_ID=${S3_ACCESS_KEY}
      - LITESTREAM_SECRET_ACCESS_KEY=${S3_SECRET_KEY}

litestream.yml:

dbs:
  - path: /data/shumoku.db
    replica:
      url: s3://my-backups/shumoku
      # MinIO など非 AWS の場合のみ:
      # endpoint: https://minio.example.com

復元は別コンテナで実行します:

docker run --rm \
  -v shumoku-data:/data \
  -v "$PWD/litestream.yml":/etc/litestream.yml:ro \
  -e LITESTREAM_ACCESS_KEY_ID=... -e LITESTREAM_SECRET_ACCESS_KEY=... \
  litestream/litestream:0.5.9 restore /data/shumoku.db

MinIO を使う場合の注意: MinIO のイメージは比較的新しい CPU（x86-64-v2 命令セット）を要求します。古い/最小構成の VM では Fatal glibc error: CPU does not support x86-64-v2 で起動しないことがあります。その場合は本物の S3 互換ストレージか、軽量な S3 プロキシ（例: gaul/s3proxy）を宛先にしてください。 Litestream 本体（replicate／restore）は影響を受けません。

アプリ改修を避けつつ定期・自動化したい場合は、対象コンテナを自動停止してから volume を固める offen/docker-volume-backup （cron・暗号化・S3・世代管理に対応）をサイドカーにする方法もあります。

いずれの方式でも、リストアを定期的に試すことが最も重要です（復元できて初めてバックアップです）。

インストール

ワンコマンドインストール（新規 Linux ホスト）

Docker（推奨）

Docker Compose オプション

バージョンの固定（本番では推奨）

アップデート

イメージの検証（署名・SBOM）

Systemd（Linux）

前提条件

インストール

管理

アップデート

手動

インストール

アップデート

リバースプロキシ（nginx）

環境変数

バックアップとリストア

本番での継続バックアップ（推奨）

目次