JSRをローカルで動かしてみよう

JSR Meetup 2024/05/03 (Fri)

Yusuke Tanaka (https://x.com/yusuktan)

はじめに

ステップバイステップでJSRをローカルで動かす方法を紹介します。

一緒に流れを追っていただいても良いですし、眺めているだけでもOKですが、時間の関係上さくさくと進めていく感じになります(maybe)。

各々のペースの差異吸収や、コマンド・URLのコピペの利便性のため、以下のURLでスライドを公開しています。適宜ご参照ください!

https://jsr-meetup-maguro.deno.dev

自己紹介

  • 𝕏: @yusuktan
  • GitHub: @magurotuna

Deno社でDeno Deployのバックエンドをやっています。

このスライドはDeno Deployでホストされています(宣伝)

JSRの目標を軽くおさらい

https://github.com/jsr-io/jsr#project-information

  • Robust
  • Low maintenance
  • Cheap
  • Open source <--- 🆒 💯 🥇 😄 🎉👍 🙌

手元でビルドして動かせる!

このセッションの目標

  • ローカルでJSRを動かせるようになる
  • ローカルで立ち上げたJSRにパッケージをpublishしてみる
  • データの処理の流れをざっっっっくりと理解する

※ 想定環境は macOS or Linux です

Q. ローカルで動かせると何が嬉しい?

A. どういう仕組みで動いているのかをいろいろ試しながら理解できる。やる気と根気と時間があればコントリビュートもできる。

おおまかな手順

だいたいREADMEに書いてあります ‍🤫

  1. まずフロントエンドだけ手元で(本番のバックエンドに接続)
  2. バックエンドも含めて全部手元で動かす
    • 必要なツールのインストール
    • 環境変数の設定
    • Postgresの設定
    • 起動、動作確認

1-1 Denoをインストール

Denoはインストール済みですか?

→ まだの場合は、deno.com の一番上のコマンドを実行 🦕

→ インストール済みの場合は、一応最新(v1.43.1)にする

$ deno upgrade
$ deno --version
deno 1.43.1 (release, aarch64-apple-darwin)
v8 12.4.254.12
typescript 5.4.3

1-2 git clone

リポジトリをもってきます。

$ git clone https://github.com/jsr-io/jsr.git

$ cd jsr

1-3 /etc/hosts を編集

ローカルでは jsr.test というドメインを使っていきます。

以下の内容を /etc/hosts に追記します。

127.0.0.1       jsr.test
127.0.0.1       api.jsr.test
127.0.0.1       npm.jsr.test

1-4 立ち上げる!

なんとこれだけでフロントエンドを立ち上げることができます。

$ deno task prod:frontend

しばらく待つと 🍋 Fresh ready と表示されます。

http://jsr.test を開いてみましょう!

本当にローカルで立ち上がってるの?という方は frontend/routes/index.tsx
をいじってみてください。変更が反映されるのが確認できます。

2-1. バックエンドもやっていく

先ほどのフロントエンドは終了しておいてください。

バックエンドに必要なツールなどをインストールします。

2-2. 環境変数の設定

GitHub Appを作る必要があり、少し面倒です。

  1. https://github.com/settings/apps/new から新しいGitHub Appを作成
    • Callback URL: http://jsr.test/login/callback
    • Request user authorization (OAuth) during installation にチェック
    • Webhook を無効化
    • Permissions -> Accout permissions -> Email addresses を Read-only にする
  2. api/.env.exampleapi/.env にコピー
  3. GITHUB_CLIENT_IDGITHUB_CLIENT_SECRET にstep1で作成したものを入れる
  4. DATABASE_URL<usrname-and-password>user:password に書き換え

2-3. PostgreSQL

DockerでPostgreSQLを立ち上げ、マイグレーションを実行します。

$ docker compose up -d postgres
$ cd api
$ cargo sqlx migrate run
$ cd ..

2-4. 各種コンポーネントを立ち上げる

以下の3つのコマンドを別々のターミナルで実行します。

$ deno task services:<macos|linux>
$ deno task dev:api
$ deno task dev:frontend

http://jsr.test にアクセスすると、すべてがローカルで立ち上がった状態のJSRが確認できます。

2-5. ローカルJSRにpublishしてみる

deno publish コマンド実行時に JSR_URL 環境変数を設定することで、ローカルのJSRにパッケージをpublishすることができます。

publishするために適当なパッケージを用意します。

$ deno init my-awesome-package
$ cd my-awesome-package

2-5. ローカルJSRにpublishしてみる(続)

deno.json が以下のような内容になるよう追記します。

{
  "name": "@<your-scope-name>/my-awesome-package",
  "version": "0.1.0",
  "exports": "./main.ts"
}

準備ができました。publishしてみましょう!

$ JSR_URL=http://jsr.test deno publish

DBを眺めてみる

DBにどんなレコードが保存されているのかを確認してみましょう。

$ psql -h localhost -p 5432 -U user -d registry
  • users ユーザー情報
  • packages パッケージ情報
  • publishing_tasks publish時の処理に関する情報
    etc...

traceを眺めてみる

JSRのAPIサーバー実装ではOpenTelemetryベースのトレーシングが整備されています。

http://localhost:16686 で立ち上がっているJaegerでトレースを眺めることができるので、ちょっと見てみましょう。

JSRをもっと知る

これでローカルでJSRを立ち上げることができるようになりました。

さらに深くJSRを理解したい方は、コードを読んだりいじったりしながらミクロな挙動を追ってみるのも良いと思いますし、マクロな視点でのざっくりとしたアーキテクチャを把握するためには、JSRチームのリードであるLucaが書いた以下の記事を読むのもおすすめです。

How we built JSR (https://deno.com/blog/how-we-built-jsr)

One more thing...

  • JSRのバックエンドはRustで実装されていますが、コードはかなりDeno Deployのそれに近いです。おそらく世界的にもまだ珍しいRustで書かれたWebバックエンド実装で、実際に本番運用されているものがオープンソースで公開されているというのは、とても参考になるのではと思います
  • このスライドはMarpで作成しました。MarpのCLIはNode.js製ですが、deno run npm:@marp-team/marp-cli で何の問題もなくDenoで動きました。必ずしも信頼しきれないNode.jsプログラムを実行するときにDenoを使うことで、余計なネットワークアクセスをしていないかどうかなどを確認しながら実行することができます。おすすめです。