β版の導入手順書
Windowsでまず試す場合は、かんたん導入の始め方へ進んでください。 名前・メールアドレス・パスワードの入力で準備できる導入アプリを用意しています。このページ以下は手動導入・保守向けの詳細です。
Windows 11またはUbuntu 24.04 LTSへ、open-hoikuictを新規導入するための手順書です。OSは導入済みとし、Python・Gitの準備から、初期管理者の作成、起動・停止、データの保存と復旧までを扱います。
初版：2026年9月22日。 記述の基準はmainの 7cafb09cad1f1eee972883f2c3fac14673873b35 です。これは手順を揃えるための基準コミットで、正式なβリリースタグではありません。配布担当者が別の版を指定する場合は、その版の手順書・変更履歴と組み合わせます。
1. 対象と到達点
| 項目 | この手順で用意するもの |
|---|---|
| 対象OS | Windows 11（x64）／Ubuntu 24.04 LTS（amd64） |
| 導入方式 | Python 3.12の仮想環境。Dockerは不要 |
| 利用範囲 | 導入したPCから、架空データで試用するローカルβ |
| DB | SQLite。既存の開発・本番DBと分けた新規DB |
| 認証 | 職員・保護者ともパスワード認証 |
| アクセス先 | http://127.0.0.1:8001/ |
| メール | capture。実際のメールは配送しない |
| キオスク・Web Push | 初回は無効 |
| 自動起動・自動バックアップ | この構成では設定しない。起動と退避は手動 |
実データを扱う園内・園外の利用には、施設で利用するための追加準備が必要です。 この手順の完了は、施設での運用開始や全機能の実機検証完了を意味しません。
「β」は試用の呼び方です。設定の HOIKUICT_ENV は development を使います。beta という値は使えません。
2. OS別の手順へ進む
- Windows 11版：PowerShellで実行します。
- Ubuntu 24.04 LTS版：端末のBashで実行します。
どちらも最初に、専用フォルダーを作り、同じ基準版を取得します。既に使っているフォルダーでは初回コマンドを実行しないでください。コマンドが失敗したら、その段階の原因を直してから次へ進みます。
導入担当者は、次の記録を残します。秘密鍵・パスワード・有効化コードはこの表に記入しません。
| 記録するもの | 記入欄 |
|---|---|
| 導入日・担当者 | |
| PC名・OS・CPU構成 | |
Pythonの版（3.12.x） |
|
| 導入フォルダーの絶対パス | |
導入したコミット（git rev-parse HEAD） |
|
| アクセスURL・ポート | |
| 退避先・最新の退避日時 | |
| 試用で見つかった問題・問い合わせ先 |
3. 設定と保存先を理解する
OS別手順の設定作成コマンドは、.env.beta.example から .env.beta.local を作り、用途の異なる2つの秘密鍵を個別に生成します。既に同名ファイルがある場合は上書きせず停止します。
| 設定 | 値・役割 |
|---|---|
HOIKUICT_ENV |
development |
HOIKUICT_ENABLE_MOCK_AUTH |
0 |
HOIKUICT_STAFF_AUTH_MODE / HOIKUICT_PARENT_AUTH_MODE |
local_password |
HOIKUICT_SECRET_KEY |
自動生成した固定値。再起動のたびに変更しない |
HOIKUICT_LOGIN_THROTTLE_HMAC_KEY |
別に生成した固定値。ログイン試行制限に使う |
HOIKUICT_DATABASE_URL |
sqlite:///./hoikuict-beta-auth.db |
HOIKUICT_CSRF_ENFORCE / HOIKUICT_COOKIE_SECURE |
ローカルHTTPでは 1 / 0 |
HOIKUICT_PARENT_MAIL_TRANSPORT |
capture |
HOIKUICT_PARENT_REGISTRATION_BASE_URL |
http://127.0.0.1:8001 |
HOIKUICT_KIOSK_ACCESS_MODE / HOIKUICT_PUSH_TRANSPORT |
disabled / disabled |
この手順では .env.example を .env にコピーしません。そちらはモック認証用です。また、シェルに設定済みの環境変数はUvicornの --env-file より優先されます。以前の開発・本番設定が残っていると、別DBに接続するなどの原因になります。
保存先は次のとおりです。フォルダーによっては、該当機能を初めて使ったときに作成されます。
| 保存対象 | 専用の導入フォルダーからの相対パス |
|---|---|
| 業務・認証・写真・保育計画 | hoikuict-beta-auth.db。稼働中は同名の -wal / -shm も使用 |
| 施設独自の文例 | data/facility.sqlite |
| 添付・各種の一時保存など | storage/、その他の機能別保存先 |
| 設定・固定の秘密鍵 | .env.beta.local |
| アプリと配布文例 | 取得したソース一式と gen_bunnrei/ 内の配布DB |
DBのファイル名だけを変えても、添付や文例DBは分離されません。 このため、β用のcloneを他環境と別フォルダーに作ります。保存先を独自変更する場合は保存先一覧とバックアップ仕様で対象を確認します。
稼働DBはOneDrive等の同期対象フォルダーやネットワーク共有へ置かず、PCのローカルディスクを使います。設定・データのコピーは管理できる保管先に置き、Gitや公開Issueへ登録しません。
4. 管理者作成時に入力するもの
初回のCLIは以下を順に質問します。ローカル試用では、例えばこのような架空の値を使います。
| 質問 | 試用での入力例 |
|---|---|
| 表示名 | 試用管理者 |
| 連絡先メールアドレス | admin@example.test |
| ログインID | beta-admin |
| 作成理由 | β版の導入確認 |
| 実行者 | 試用担当者 |
| 承認者 | 試用責任者 |
| この内容で作成しますか | 内容を確認して yes |
パスワードはCLIで入力しません。作成後に表示される有効化コード（6文字・30分有効）を、本人がブラウザーの /staff/activate へ入力します。続く確認画面で対象職員・ログインIDを確認し、8文字以上のパスワードと確認用パスワードを入力します。
すでに職員がいるDBでは bootstrap-admin は停止します。DB削除や再作成ではなく、接続先を確認し、必要ならOS別手順の activate-staff で対象職員のコードを再発行します。
5. 最初の動作確認
OS別手順で管理者としてログインしたら、次を順に確認します。
| 確認 | 合格の目安 | 結果・日付 |
|---|---|---|
/healthz |
{"status":"ok"} が表示される |
|
| 職員認証 | 自分で設定したID・パスワードでログインできる | |
| 初期状態 | 業務デモの園児・家庭が混入していない | |
| 基本データ | 画面から架空のクラス・家庭・園児を各1件登録し、再表示できる | |
| 職員権限 | 試用職員を追加し、閲覧専用では更新できないことを確認できる | |
| 添付 | 利用予定の機能で架空の添付を保存し、開ける | |
| 再起動 | アプリを停止・再起動してもアカウント・記録・添付が残る | |
| 退避と復旧 | OS別の退避手順で保存し、復旧後も同じ内容を確認できる |
登録画面は日々の業務、アカウント、画面・URL一覧から確認できます。通常起動は業務デモデータを自動投入しません。認証βでデモ投入の --wipe-all は使いません。
保護者の招待・メール確認、管理者のメール復旧について、capture ではメールが受信箱へ届きません。メール到着を前提とする一連の確認は施設利用の追加準備後、担当者が受信できるテスト用アドレスで行います。Web Pushとキオスクも、初期設定では動作確認済みと記録しません。
6. 退避・復旧・更新の考え方
OS別手順には、このローカルβを完全に停止してフォルダー全体を退避する方法を記載しています。これには設定・秘密鍵・DB・添付を含みます。保存先を導入フォルダーの外へ変更した場合は、その保存先も同じ停止期間中に退避します。
この退避フォルダーはアプリのバックアップCLIが作る形式1・形式2とは異なり、管理画面の「復元」へ読み込ませるものではありません。施設運用のバックアップは正式な作成・検証・復元手順を使います。
この手順ではbackup-worker・restore-worker・復元gatewayを起動していません。管理画面で依頼を登録しただけでは、自動バックアップや園全体の復元ができる構成にはなりません。
更新は、新規導入コマンドを既存フォルダーで繰り返す操作ではありません。
- 更新担当者が更新元・更新先のコミットと最新の変更・配備記録を確認します。
- 停止退避を取得し、その版・設定へ復旧できることを確認します。
- 退避のコピーと更新先のコードを使った別環境で、DBの更新と既存機能を確認します。
- 確認した版を適用し、初期管理者・秘密鍵を作り直さず、ログイン・件数・添付・バックアップを照合します。
- スキーマ更新後に旧コードだけへ戻さず、更新前データ・設定との組を使って切戻しを判断します。更新後に入力があれば、その保全方法も決めます。
2026年9月22日の統合記録ではmainの新規バックアップは形式2、同日時点の本番配備版は形式1です。ブランチ名や「最新」という理由だけで、本番へ上書きしません。
7. 施設で利用するための追加準備
別PC・タブレット・保護者の端末から利用する構成は、次の項目を決めてから構築・検証します。ローカル起動コマンドの 127.0.0.1 を 0.0.0.0 に変えるだけでは完成しません。
| 項目 | 準備・確認する内容 | 詳細 |
|---|---|---|
| 稼働環境 | 専用の実行ユーザー、起動管理、OS再起動後の復帰、スリープ対策、保存領域の権限 | 運用試験の条件 |
| HTTPS・アクセス経路 | 施設URL、TLSを終端するプロキシ、接続を許可する範囲、直接アクセスの制限 | 本番設定 |
| 本番認証 | HOIKUICT_ENV=production、Secure Cookie・CSRF、固定鍵、禁止パスワードリスト、信頼するプロキシIP/CIDR |
本番設定 |
| メール | SMTP・STARTTLS、送信元・資格情報、HTTPSの登録URL、登録・管理者復旧の受信試験 | アカウント |
| キオスク・通知 | 使用する場合の端末認証、Web Push鍵・公開origin、各端末での受入 | キオスク／Web Push |
| バックアップ | 全保存対象、停止方式、必要なworker、別系統保存、暗号化、隔離復元試験 | バックアップ検証 |
| 利用開始 | 対象者・業務範囲、担当者、障害時の代替手段、取扱ルール、受入記録 | リリース確認 |
このページの手動導入はローカル試用までを対象にしています。Windowsのサービス・HTTPS・SMTP・バックアップを導入アプリで設定する場合は、Windowsの段階別導入手順へ進んでください。TrueNASはTrueNAS導入ガイドが入口です。Ubuntuのsystemdによる常駐と一般Linux向けのHTTPS配備は、この手順書の導入・実機検証には含めていません。
8. この手順書の確認範囲
設定名・CLI引数・初期管理者の動作は基準コードと照合しています。2026年9月22日、Windows上の既存Python 3.13.7を使い、基準コミットを展開した隔離フォルダーと新規DBで次を確認しました。
- 両OSの設定生成処理が同じ内容で、UTF-8で保存し、既存の設定を上書きしないこと。
- 記載したCLIによる設定検査・初期管理者作成。
- 実HTTPでの起動確認、CSRFを有効にした2段階の有効化、パスワードログイン。
- 正常停止・再起動後のログインと、初期管理者・施設文例DBの保持。
- MkDocsのstrictビルドと内部リンクの検査。
Python 3.12はリポジトリのCI・Dockerの基準です。上記はPython 3.12での新規導入試験の代わりにはなりません。Windows 11／Ubuntu 24.04 LTSを新規構築して、依存ライブラリの導入から退避・復旧まで通す試験は別途必要です。OS・Python・対象コミット・操作結果を第2章と第5章に記録し、未実施の項目は合格にしません。