Huly Platform

⭐️ あなたのスターが私たちの励みになります。GitHub でスターをお願いします！

概要

Huly Platform は、CRM システムなどのビジネスアプリケーションの開発を加速するために設計された堅牢なフレームワークです。このリポジトリには、チャット、プロジェクト管理、CRM、HRM、ATS などの複数のアプリケーションが含まれています。 Huly や TraceX をはじめ、さまざまなチームがこの Platform 上でプロダクトを構築しています。

Huly

セルフホスティング

Huly の開発への変更や貢献を目的とせず、主にセルフホスティングに関心がある場合は、huly-selfhost をご利用ください。このプロジェクトは docker を使用して Huly をホストする便利な方法を提供しており、簡単なセットアップで手軽に利用できるよう設計されています。自前のサーバーで Huly を気軽にお楽しみください。

アクティビティ

Alt

API クライアント

Huly をプログラムから操作したい場合は、API クライアントのドキュメントをご覧ください。API クライアントは、すべての Huly 操作に対する型付きインターフェースを提供しており、連携機能やカスタムアプリケーションの構築に利用できます。

API の使用例は Huly examples リポジトリでご確認いただけます。

変更履歴

各バージョンの変更点、改善点、バグ修正の詳細については、変更履歴をご覧ください。

バージョン

Huly Platform では、本番リリースと開発リリースを区別するために 2 種類のバージョンタグを使用しています：

本番バージョン (v*) - エンドユーザー向けの安定リリース
- 例: v0.7.310, v0.7.307, v0.6.501
- 本番環境へのデプロイに推奨されるバージョン
- セルフホスト環境に適しています
- GitHub Releases でリリースノートとともに公開
開発バージョン (s*) - 開発者向けのプレリリースビルド
- 例: s0.7.313, s0.7.292, s0.7.288
- 開発およびテスト目的で使用
- 実験的な機能やバグ修正を含む場合があります
- 本番環境での使用は推奨されません

アーキテクチャ

プラットフォームのアーキテクチャ、サービス、およびそれらの相互作用の詳細については、アーキテクチャ概要をご覧ください。

前提条件

作業を開始する前に、システムが以下の要件を満たしていることを確認してください：
- Node.js (v20.11.0 が必要)
- Docker
- Docker Compose

動作確認

インストールを確認するには、ターミナルで以下のチェックを行ってください：

docker コマンドが利用可能であることを確認します：

docker --version
docker compose version

ブランチとコントリビューション

main ブランチは、本番デプロイに使用されるデフォルトブランチです。バージョンがコミュニティで利用できる状態になると、staging ブランチからこのブランチに変更がマージされます。
staging ブランチは、プレリリーステストに使用されます。テストには十分安定していますが、本番デプロイにはまだ準備ができていません。
develop ブランチは開発に使用され、コントリビューションのデフォルトブランチです。

私たちは定期的に develop を staging にマージしてテストビルドを行います。プレリリースデプロイでビルド品質に満足したら、変更を main にマージしてコミュニティに新バージョンをリリースします。

開発環境のセットアップ

communication サブモジュールの初期化

git submodule init
git submodule update

communication サブモジュールの更新

git submodule update

認証

このプロジェクトは依存関係の管理に GitHub Packages を使用しています。依存関係を正常にダウンロードするには、GitHub の個人アクセストークンを生成し、そのトークンで npm にログインする必要があります。

以下の手順に従ってください：

GitHub トークンの生成：

GitHub アカウントにログイン
Settings > Developer settings > Personal access tokens (https://github.com/settings/personal-access-tokens) に移動
Generate new token をクリック
必要なスコープを選択（最低限 read:packages）
トークンを生成してコピー

npm での認証：

npm login --registry=https://npm.pkg.github.com

プロンプトが表示されたら、GitHub のユーザー名を入力し、生成したトークンをパスワードとして使用してください

クイックスタート

sh ./scripts/fast-start.sh

インストール

アプリケーションのインストールには Microsoft の rush が必要です。

以下のコマンドで Rush をグローバルにインストールします：

npm install -g @microsoft/rush

リポジトリのルートに移動して以下のコマンドを実行します：

rush install
rush build

または、以下を実行するだけでも構いません：

sh ./scripts/presetup-rush.sh

ビルドと実行

開発環境のセットアップにはシステムに Docker がインストールされている必要があります。

Linux と macOS の両方で amd64 と arm64 コンテナがサポートされています。

cd ./dev/
rush build    # 必要なパッケージをすべてビルドします。
# rush rebuild  # ビルドキャッシュを無視する場合に使用できます。
rush bundle   # バンドルを準備します。
rush package  # すべての webpack パッケージをビルドします。
rush validate # TypeScript ですべてのソースを検証し、ts-node 実行に必要な d.ts ファイルを生成します。
rush svelte-check # オプション。svelte-check を使用した svelte ファイルの検証。
rush docker:build   # ローカル Docker 環境ですべてのアプリケーションの Docker コンテナをビルドします。
rush docker:up # すべてのコンテナを起動します

rush docker:build は build、bundle、package などの必要なフェーズをすべて自動的に実行することに注意してください。

注意: リソースが限られたマシンでは、軽量バリアント rush docker:min と rush docker:up:min を使用して、必要なサービスのみをビルド・実行できます（hulypulse、redis、process、backup、rating、preview、link-preview、elastic、fulltext、payment、stats、print、sign、hulygun、hulykvs を除外）。

または、以下を実行するだけでも構いません：

sh ./scripts/build.sh

デフォルトでは、MongoDB、Elasticsearch、MinIO のインスタンス用に dev_db、dev_elastic、dev_files という名前の Docker ボリュームが作成されます。

hosts ファイルに以下の行を追加してください：

macOS / Linux: /etc/hosts
Windows: C:\Windows\System32\drivers\etc\hosts

127.0.0.1 huly.local
::1 huly.local

URL http://huly.local:8087 にアクセスすると、開発モードのアプリが表示されます。

制限事項：

ローカルインストールではメール送信がサポートされていないため、パスワードリカバリーやメール通知などの機能が無効になります。

開発モードでの実行

開発モードでは、ライブリロードとスムーズな開発プロセスが可能です。

cd dev/prod
rush validate
rushx dev-server

その後 http://localhost:8080 にアクセスしてください。

右パネルの「Sign up」を選択し、下部の「Sign up with password」リンクをクリックします。新しいユーザーの認証情報を入力し、ワークスペースの作成に進みます。

プロジェクト構造とデータベースの更新

プロジェクトの構造が更新された場合、プロジェクトの再リンクと再ビルドが必要になることがあります。

rush update
rush build

トラブルシューティング

ビルドが失敗してもコードが正しい場合は、ビルドキャッシュを削除して再試行してみてください。

# プロジェクトルートから
rm -rf common/temp/build-cache

ビルド & ウォッチ

開発目的で rush build:watch アクションを使用できます。

ウォッチモードでビルドと検証のフェーズが含まれます。

テスト

ユニットテスト

rush test # すべてのテストを実行

rushx test # パッケージディレクトリ内で個別のテストを実行

UI テスト

cd ./tests
rush build
rush bundle
rush docker:build
## テスト用 Docker コンテナを作成し、テストデータベースをセットアップ
./prepare.sh
## UI テストを実行
rushx uitest

開発環境でテストを実行するには、以下の手順に従ってください：

cd ./tests
./create-local.sh ## ワークスペースを事前定義された初期状態に復元するだけの場合は ./restore-local.sh を使用
cd ./sanity
rushx dev-uitest # 開発環境に対してすべてのテストを実行
rushx dev-debug -g 'pattern' # マッチするテストパターンのみをデバッグモードで実行

パッケージの公開

node ./common/scripts/bump.js -p projectName

追加テスト

このプロジェクトは BrowserStack でテストされています。

WSL ビルドガイド

このガイドでは、Windows と WSL の両方からアクセス可能な NTFS ドライブ上のソースコードからアプリケーションをビルド・実行する際の注意点を説明します。

前提条件

ディスク容量の要件

十分なディスク容量があることを確認してください：

クリーンな Docker にフルデプロイしたローカルアプリケーションは、WSL 仮想ディスク容量を 35 GB 以上消費します
ビルド後のアプリケーションフォルダ（ソース＋成果物）は 4.5 GB を占有します

システムドライブ（通常 C:\）の容量が不足している場合は、Docker Settings → Resources → Advanced で仮想ディスクの場所を変更できます。

Docker WSL 統合

Docker が WSL からアクセス可能であることを確認してください：

Docker Settings → Resources → Advanced → WSL Integration に移動
アプリケーションのビルドと実行を行うディストリビューションを選択
WSL で以下のコマンドを実行して統合が機能することを確認：
```
docker run hello-world
```

よくある問題と解決策

Windows での Git の改行コード

Windows の Git は改行コードを自動的に変換することがよくあります。ほとんどのビルドスクリプトは .sh ファイルであるため、Windows でのチェックアウトがファイルを壊さないようにしてください。

解決方法：

Windows ではなく WSL からチェックアウトする
Windows の Git で自動変換を無効にする：
```
git config --global core.autocrlf false
```
これにより、マシン上のすべてのリポジトリで自動変換が無効になります。

WSL での管理者権限

WSL で作業する際、一部のコマンドには管理者権限が必要です。Ubuntu ディストリビューションを使用している場合は、コマンドに sudo を付けてください：

sudo npm install -g @microsoft/rush

WSL の設定

ソースコードが Windows の NTFS ドライブに配置されている場合、WSL の /etc/wsl.conf ファイルを編集し（例: sudo nano /etc/wsl.conf）、以下の内容が存在しない場合は追加してください：

[automount]
enabled = true
root = /mnt/
options = "metadata,umask=22,fmask=11"

[interop]
appendWindowsPath = false

ただし、ビルドとメンテナンス操作のパフォーマンスが大幅に向上するため、リポジトリを WSL ディスク上に保存することをお勧めします。

アプリケーションの実行

これらの準備が整えば、ビルド手順は問題なく動作するはずです。

ポートの競合

アプリケーションの起動時（rush docker:up）、Windows の一部のネットワークポートが使用されている場合があります。\dev\docker-compose.yaml ファイルでポートマッピングを修正できます。

重要: 変更するポートによっては、以下の操作が必要です：

そのポートを使用しているものを特定する
対応するサービス設定で新しいアドレスを更新する

platform

Huly Platform

概要

セルフホスティング

アクティビティ

API クライアント

変更履歴

バージョン

アーキテクチャ

目次

前提条件

動作確認

ブランチとコントリビューション

開発環境のセットアップ

communication サブモジュールの初期化

communication サブモジュールの更新

認証

クイックスタート

インストール

ビルドと実行

開発モードでの実行

プロジェクト構造とデータベースの更新

トラブルシューティング

ビルド & ウォッチ

テスト

ユニットテスト

UI テスト

パッケージの公開

追加テスト

WSL ビルドガイド

前提条件

ディスク容量の要件

Docker WSL 統合

よくある問題と解決策

Windows での Git の改行コード

WSL での管理者権限

WSL の設定

アプリケーションの実行

ポートの競合