GLATasks

外観

開発手順 ​

開発環境の構築手順 ​

必要環境 ​

  • LinuxまたはmacOS
  • Docker / Docker Compose
  • uv
  • Node.js

セットアップ手順 ​

すべてのmakeコマンドはプロジェクトルートから実行する （app/へ移動して実行すると${PWD}がずれてMakefile内のパス解決が誤動作する）。

  1. 本リポジトリをclone

  2. .env-exampleを.envにコピーして環境変数を設定

    bash
    cp .env-example .env

    COMPOSE_PROFILE・DATA_DIR・UID・GIDを環境に合わせて編集する

  3. 開発環境のセットアップを実行

    bash
    make setup

  4. 起動

    bash
    make deploy

開発コマンド ​

コマンド内容
make format整形 + 軽量lint + 自動修正
make test全チェック実行（コミット前の必須検証）
make test-e2ee2eテスト（Playwright）単独実行
make update依存更新

e2eテスト（make test-e2e）は開発環境（make deploy）が起動している必要がある。

サプライチェーン攻撃対策 ​

npm / PyPIレジストリへの悪意あるパッケージ公開に対し、次の方針を採用する。

  • npmパッケージ: pnpm-workspace.yamlのminimumReleaseAge: 1440で公開から1日未満のインストールを禁止する
  • PyPIパッケージ: uv.tomlのexclude-newer = "1 day"で公開から1日未満のインストールを禁止する
  • pnpm installは--frozen-lockfileを明示してロックファイル乖離時の再resolveを禁止する
  • .pre-commit-config.yamlのadditional_dependenciesはバージョンを固定する（@latestは使わない）

依存更新はmake updateを使う。

Docker構成 ​

サービス構成・環境変数はcompose.yaml / .envを参照。 プロファイルはproduction（既定推奨）とdevelopmentの2種類がある。

DBマイグレーション運用 ​

自動適用 ​

make deploy（docker compose up）の起動時にマイグレーションが自動適用される。 稼働中のappを止めずに即座にマイグレーションを反映したい場合はmake migrateを実行する。

マイグレーションファイルの追加 ​

新規スキーマ変更は必ずpnpm run db:generate経由で生成する。 drizzle/migrations/meta/_journal.jsonのwhen値（UNIXミリ秒）は直前エントリより大きくなければならない。 別ブランチで生成したmigrationのmergeで順序が逆転する場合は、新しい側のwhenを再生成してからcommitする。

履歴整合のリカバリー ​

DBが半端な状態になった場合はmake sqlから__drizzle_migrationsテーブルと実DB状態を整合させる。 整合手順を実行する前に必ずmake backupを取得する。

典型例として、make start時にmigrate-devがexit 1で失敗し ALTER TABLE ... ADD ... Duplicate column nameが出る場合がある。 drizzle-kit pushでスキーマを先行適用すると実スキーマは最新だが __drizzle_migrationsに当該マイグレーションが記録されず、再適用で重複エラーになる。 実スキーマが当該マイグレーション到達済みであることを確認したうえで、 __drizzle_migrationsへ記録行を1行挿入して整合させる。 hashは当該マイグレーションSQLファイル全文のsha256、created_atは drizzle/migrations/meta/_journal.jsonの当該エントリのwhen値を用いる。

CI/CD ​

masterへのpushおよびPR時にci.yamlが自動実行される（.github/workflows/ci.yaml参照）。 masterへのpushでdocs/配下に変更があればdocs.yamlワークフローが自動実行され、 GitHub Pagesへデプロイされる。

ドキュメントサイト運用 ​

bash
make docs

http://localhost:5173/GLATasks/でプレビューできる。

バックアップとリストア ​

バックアップ ​

bash
make backup

バックアップ先: ${DATA_DIR}/backups/YYYYMMDD_HHMMSS/（DBダンプ + キーファイル）。 既定で直近5世代を保持する（BACKUP_KEEP環境変数で変更可能）。 DBコンテナが停止中の場合はエラー終了する。初回デプロイなどDBがない状態ではSKIP_DB_DUMP=1でスキップ可能。

リストア ​

${DATA_DIR}/backups/YYYYMMDD_HHMMSS/配下のSQLとキーファイルをDBコンテナへリストア後、 make restart-appを実行する。

リリース手順 ​

事前にghコマンドをインストールしてgh auth loginでログインしておく。次のいずれかを実行。

bash
gh workflow run release.yaml --field="bump=PATCH"
gh workflow run release.yaml --field="bump=MINOR"
gh workflow run release.yaml --field="bump=MAJOR"

進捗はhttps://github.com/ak110/GLATasks/actionsで確認できる。