Getting Started

Quden開発へようこそ！このガイドでは、ローカル開発環境を構築し、Qudenの開発を開始するための全手順を説明します。

前提条件

ローカル開発を始める前に、以下のツールをインストールしてください。

必須ツール

ツール	推奨バージョン	インストール方法
Node.js	v20.x以上	https://nodejs.org/
Yarn	v1.22.x以上	`npm install -g yarn`
Docker	最新版	https://www.docker.com/
Docker Compose	最新版	Docker Desktopに含まれる
Git	v2.x以上	https://git-scm.com/
mkcert	最新版	https://github.com/FiloSottile/mkcert

オプションツール

ツール	用途
MongoDB Compass	ローカルDBの確認・デバッグ
AWS CLI	本番デプロイ時に必要

mkcertのインストール

ローカル開発でHTTPS通信を行うため、mkcertが必要です。

bash

# macOS
$ brew install mkcert
$ mkcert -install

# Windows（Chocolatey使用）
$ choco install mkcert
$ mkcert -install

リポジトリ

Qudenは複数のリポジトリで構成されています。

GitHubプロジェクト管理

GitHub プロジェクト
- 各リポジトリの issue をまとめて管理
- カンバンボードでタスクの進捗を管理

メインリポジトリ一覧

リポジトリ	説明	技術スタック
quden	大タスク管理用	-
toruca-frontend-web	Webフロントエンド	Next.js, TypeScript
toruca-backend-core	バックエンドAPI	NestJS, TypeScript
toruca-infra	インフラコード	Terraform, AWS
toruca-chrome-extension	Chrome拡張機能	TypeScript
quden-desktop-app	デスクトップアプリ	Electron
quden-desktop-app-update-server	アップデートサーバー	Node.js
wiki-dev	Wiki開発	-
quden-transcoder	動画変換	AWS Lambda
blog	ブログ	-
knowledge-datasource	ナレッジデータベース	-

TIP

toruca は Quden の旧名です。リポジトリ名や一部コードに旧名が残っています。

環境構築

ローカル開発環境を構築するための手順を、ステップバイステップで説明します。

1. リポジトリのクローン

まず、開発に必要なリポジトリをクローンします。最低限、以下の2つが必要です。

bash

# 作業ディレクトリに移動
$ cd ~/projects  # 任意のディレクトリ

# バックエンド
$ git clone https://github.com/zipunk/toruca-backend-core.git
$ cd toruca-backend-core

# フロントエンド
$ git clone https://github.com/zipunk/toruca-frontend-web.git
$ cd toruca-frontend-web

必要に応じて、Chrome拡張やデスクトップアプリもクローンしてください。

2. 環境変数の設定

バックエンドの環境変数

toruca-backend-core のルートディレクトリに .env.development.local を作成します。

bash

$ cd toruca-backend-core
$ touch .env.development.local

環境変数の値は bitwarden で管理されています。チームメンバーに bitwarden のアクセス権限を確認してください。

最低限必要な環境変数:

shell

AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID>
AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY>
AWS_COGNITO_USER_POOL_ID=<AWS_COGNITO_USER_POOL_ID>
AWS_COGNITO_APP_CLIENT_ID=<AWS_COGNITO_APP_CLIENT_ID>
AWS_COGNITO_APP_CLIENT_SECRET=<AWS_COGNITO_APP_CLIENT_SECRET>
SENDGRID_API_KEY=<SENDGRID_API_KEY>
AWS_S3_BUCKET_FOR_VIDEO_RECORD=<AWS_S3_BUCKET_FOR_VIDEO_RECORD>
AWS_LAMBDA_CONCAT_ARN=<AWS_LAMBDA_CONCAT_ARN>
AWS_CLOUDFRONT_KEY_PAIR_ID=<AWS_CLOUDFRONT_KEY_PAIR_ID>
AWS_CLOUDFRONT_PRIVATE_KEY_NAME=<AWS_CLOUDFRONT_PRIVATE_KEY_NAME>
AWS_CLOUDFRONT_DOMAIN=<AWS_CLOUDFRONT_DOMAIN>
COOKIE_DOMAIN=<COOKIE_DOMAIN>

フロントエンドの環境変数

toruca-frontend-web のルートディレクトリに .env.local を作成します。

bash

$ cd toruca-frontend-web
$ touch .env.local

リポジトリの .env.development を参考に、以下の値を追加してください。

plain

SENTRY_SERVER_INIT_PATH=XXXXXXXXXXXXXXXXXXXXXXXXXX
SENTRY_AUTH_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXX

NOTE

bitwarden の frontend/.env.local メモに記載されている情報は古い可能性があります。まずはリポジトリの .env.development を参照してください。

3. HTTPS化の設定

ローカル開発では、CloudFront の署名付きCookieを使用するため、HTTPS通信が必要です。

証明書の発行

mkcert を使って、ローカル用のSSL証明書を発行します。

bash

# ローカル認証局をインストール（初回のみ）
$ mkcert -install

# local.dev.quden.io 用の証明書を発行
$ mkcert local.dev.quden.io

実行すると、以下の2ファイルが生成されます：

local.dev.quden.io.pem（公開鍵）
local.dev.quden.io-key.pem（秘密鍵）

証明書の配置

発行した証明書を、各リポジトリの secrets/ ディレクトリに配置します。

バックエンド:

bash

$ cd toruca-backend-core
$ mkdir -p secrets
$ mv local.dev.quden.io.pem secrets/
$ mv local.dev.quden.io-key.pem secrets/

フロントエンド:

bash

$ cd toruca-frontend-web
$ mkdir -p secrets
$ cp ../toruca-backend-core/secrets/local.dev.quden.io.pem secrets/
$ cp ../toruca-backend-core/secrets/local.dev.quden.io-key.pem secrets/

TIP

同じ証明書をバックエンドとフロントエンドの両方で使用できます。

4. hostsファイルの設定

CloudFrontの署名付きCookieは quden.io ドメインに対して発行されるため、localhostを local.dev.quden.io としてアクセスできるようにします。

macOS / Linux

bash

$ sudo vim /etc/hosts

以下を追加：

bash

# For quden-dev
127.0.0.1 local.dev.quden.io

Windows

C:\Windows\System32\drivers\etc\hosts を管理者権限で開く
以下を追加：

127.0.0.1 local.dev.quden.io

5. バックエンドの起動

依存関係のインストール

bash

$ cd toruca-backend-core
$ yarn install

M1 Macの場合、エラーが発生したら dockerfiles/app/Dockerfile.local の先頭を以下に変更：

dockerfile

FROM --platform=linux/amd64 node:lts-alpine

Dockerコンテナの起動

bash

# HTTPSで起動
$ yarn dev:docker:up:https

初回起動時は、イメージのビルドに時間がかかります（5-10分程度）。

シードデータの投入

初回起動後、データベースにシードデータを投入します。

bash

# 別のターミナルで実行
$ yarn dev:db:seed:init

シードデータ関連コマンド:

yarn dev:db:seed:init - データを全削除してシードデータを流す
yarn dev:db:seed:clear - データの削除
yarn dev:db:seed:reset - データを削除してシードデータを改めて流す（clear + init）

起動確認

以下のURLにアクセスして、APIが起動しているか確認します。

https://local.dev.quden.io:3001/health

{"status": "ok"} のようなレスポンスが返れば成功です。

6. フロントエンドの起動

バックエンドが起動していることを確認してから、フロントエンドを起動します。

依存関係のインストール

bash

$ cd toruca-frontend-web
$ yarn install

Dockerコンテナの起動

bash

# HTTPSで起動
$ yarn dev:docker:up:https

フロントエンドは、バックエンドのDockerネットワーク（toruca-network）に依存しているため、バックエンドが先に起動している必要があります。

7. 動作確認

ブラウザでアクセス

以下のURLにアクセスします。

https://local.dev.quden.io:3000/

デモユーザーでログイン

ローカル環境では、以下のデモユーザーでログインできます。

plain

EMAIL: test+0@toruca.com
PASSWORD: Password1234

ログイン後、クリップ一覧や動画再生ができれば、環境構築は完了です！

よくあるエラーと対処法

ポート競合エラー

エラー: Error: listen EADDRINUSE: address already in use :::3000

原因: 既に別のプロセスがポート3000または3001を使用している

対処法:

bash

# ポートを使用しているプロセスを確認
$ lsof -i :3000
$ lsof -i :3001

# プロセスを停止
$ kill -9 <PID>

MongoDB接続エラー

エラー: MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27018

原因: MongoDBコンテナが起動していない

対処法:

bash

# Dockerコンテナの状態を確認
$ docker ps

# バックエンドコンテナを再起動
$ cd toruca-backend-core
$ yarn dev:docker:down
$ yarn dev:docker:up:https

ERR_SSL_PROTOCOL_ERROR

エラー: ブラウザに ERR_SSL_PROTOCOL_ERROR と表示される

原因: ローカル認証局がインストールされていない

対処法:

bash

$ mkcert -install

その後、ブラウザのキャッシュをクリアして再度アクセスしてください。

node-canvasのinstallに失敗する

エラー: yarn install 時にnode-canvasのコンパイルエラー

原因: 必要なシステムライブラリが不足している

対処法（macOS）:

bash

$ brew install pkg-config cairo pango libpng jpeg giflib librsvg pixman

その後、yarn install を再実行してください。

コンテナ起動時のエラー（M1 Mac）

エラー: yarn install の途中で止まってしまう

原因: M1 Macのアーキテクチャ非互換

対処法:

dockerfiles/app/Dockerfile.local（バックエンド）またはDockerfile.local（フロントエンド）の先頭を以下に変更：

dockerfile

FROM --platform=linux/amd64 node:lts-alpine

環境変数の設定ミス

エラー: サインインできない、API呼び出しが失敗する

原因: .env.development.local または .env.local の設定が不正

対処法:

bitwarden の環境変数を再確認
.env.development（リポジトリ内）と比較
環境変数ファイルを修正後、コンテナを再起動

bash

$ yarn dev:docker:down
$ yarn dev:docker:up:https

`yarn add` で新たにライブラリを追加した場合

エラー: ライブラリが見つからない（can't resolve）

原因: コンテナ内のnode_modulesが更新されていない

対処法:

bash

# イメージを再ビルド
$ yarn dev:docker:build_up

古いイメージを削除（推奨）:

bash

$ docker image prune

Dockerのresourceが足りない

エラー: error Command failed with signal "SIGKILL"

原因: Dockerのメモリ不足

対処法:

Docker Desktop の設定を開く
Resources → Memory を増やす（8GB以上推奨）
Apply & Restart

サインインできない

原因（複数考えられる）:

DBにシードデータが投入されていない
Cognito環境変数が不正
ブラウザのキャッシュが原因

対処法:

シードデータの再投入
bash
```
$ yarn dev:db:seed:reset
```
環境変数の再確認（.env.development.local）
ブラウザのシークレットモードで試す

Dockerコンテナの再起動

bash

$ yarn dev:docker:down
$ yarn dev:docker:up:https

pre-commit の lint が走らない

原因: huskyの設定が不足

対処法:

bash

$ yarn husky install

次のステップ

環境構築が完了したら、以下のドキュメントを読んで開発を始めましょう！

全体像を理解する

技術スタック - Qudenで使用している技術の全体像
アーキテクチャ - システムアーキテクチャの詳細

開発を開始する

バックエンド開発者:

バックエンド開発ガイド - NestJSを使った開発手順
データモデル - MongoDBのスキーマ設計
デプロイフロー - AWS ECSへのデプロイ方法

フロントエンド開発者:

フロントエンド開発ガイド - Next.jsを使った開発手順

Chrome拡張開発者:

Chrome拡張概要 - Chrome拡張の開発方法

デスクトップアプリ開発者:

デスクトップアプリ（Mac） - Electronアプリの開発

チーム文化を理解する

エンジニアリングカルチャー - 開発チームの価値観
Working Agreement - チームの運用ルール

便利なツール

ngrokの使い方 - ローカル環境を外部公開
AWS Exec - ECSコンテナへの接続方法

開発環境で使用できるメールアドレス

ユーザー登録などを開発環境で行う際にメールアドレスが必要になることがあります。

plain

メールアドレス例: test+yuki+20230501@quden.io

@quden.io または @toruca.com を使用できます
@ より前はユニークである必要があるため、日付や名前を入れてください
受信したメールは Slack の #notify_dev-email-quden チャンネルで確認できます

ローカルでDBを確認する

MongoDB Compass を使うと、ローカルのMongoDBを視覚的に確認できます。

MongoDB Compassをインストール
- 公式: https://www.mongodb.com/try/download/compass
- Homebrew: brew install --cask mongodb-compass
MongoDB Compassを起動
接続URLを入力
```
mongodb://localhost:27018/
```
接続成功すると、データベース一覧が表示されます

ステージング環境へのアクセス

開発環境（ステージング）にはBasic認証がかけられています。

URL: https://app.dev.quden.io

認証情報:

plain

username: quden-admin
password: quden9uden

その他の参考情報

アーキテクチャ詳細: Quden アーキテクチャ（Notion）
GitHub プロジェクト: https://github.com/orgs/zipunk/projects/1/views/1
採用情報: エンジニア採用

環境構築でお困りの場合は、Slackの開発チャンネルで気軽に質問してください！

Getting Started ​

目次 ​

前提条件 ​

必須ツール ​

オプションツール ​

mkcertのインストール ​

リポジトリ ​

GitHubプロジェクト管理 ​

メインリポジトリ一覧 ​

環境構築 ​

1. リポジトリのクローン ​

2. 環境変数の設定 ​

バックエンドの環境変数 ​

フロントエンドの環境変数 ​

3. HTTPS化の設定 ​

証明書の発行 ​

証明書の配置 ​

4. hostsファイルの設定 ​

macOS / Linux ​

Windows ​

5. バックエンドの起動 ​

依存関係のインストール ​

Dockerコンテナの起動 ​

シードデータの投入 ​

起動確認 ​

6. フロントエンドの起動 ​

依存関係のインストール ​

Dockerコンテナの起動 ​

7. 動作確認 ​

ブラウザでアクセス ​

デモユーザーでログイン ​

よくあるエラーと対処法 ​

ポート競合エラー ​

MongoDB接続エラー ​

ERR_SSL_PROTOCOL_ERROR ​

node-canvasのinstallに失敗する ​

コンテナ起動時のエラー（M1 Mac） ​

環境変数の設定ミス ​

yarn add で新たにライブラリを追加した場合 ​

Dockerのresourceが足りない ​

サインインできない ​

pre-commit の lint が走らない ​

次のステップ ​

全体像を理解する ​

開発を開始する ​

チーム文化を理解する ​

便利なツール ​

開発環境で使用できるメールアドレス ​

ローカルでDBを確認する ​

ステージング環境へのアクセス ​

その他の参考情報 ​

Getting Started

目次

前提条件

必須ツール

オプションツール

mkcertのインストール

リポジトリ

GitHubプロジェクト管理

メインリポジトリ一覧

環境構築

1. リポジトリのクローン

2. 環境変数の設定

バックエンドの環境変数

フロントエンドの環境変数

3. HTTPS化の設定

証明書の発行

証明書の配置

4. hostsファイルの設定

macOS / Linux

Windows

5. バックエンドの起動

依存関係のインストール

Dockerコンテナの起動

シードデータの投入

起動確認

6. フロントエンドの起動

依存関係のインストール

Dockerコンテナの起動

7. 動作確認

ブラウザでアクセス

デモユーザーでログイン

よくあるエラーと対処法

ポート競合エラー

MongoDB接続エラー

ERR_SSL_PROTOCOL_ERROR

node-canvasのinstallに失敗する

コンテナ起動時のエラー（M1 Mac）

環境変数の設定ミス

`yarn add` で新たにライブラリを追加した場合

Dockerのresourceが足りない

サインインできない

pre-commit の lint が走らない

次のステップ

全体像を理解する

開発を開始する

チーム文化を理解する

便利なツール

開発環境で使用できるメールアドレス

ローカルでDBを確認する

ステージング環境へのアクセス

その他の参考情報