hpcs-web

現在の管理者:

• @namachan10777

更新方法

必要なツール

• node, npm
• pnpm
  • npm install -g pnpmでインストールしても良い

開発環境の構築

上記ツールをインストールした上で、プロジェクトのルートディレクトリで

pnpm install
pnpm run dev

とするとlocalhostでのプレビューページのリンクがターミナルに表示されるのでそこにアクセスする。 ファイルを更新しつつ表示が問題ないか確かめ、完成したら

pnpm run fix:fmt
pnpm run build

をしてエラーと警告が出ないかを確認し、問題なければPullRequestを出して管理者にレビューをもらう。 ブランチはfix/*、feature/*、chore/*などの名前で切ることを推奨する。

ファイル構成

Web係が通常編集対象とするのは以下のファイルです。 他のページは以下のファイルの更新に合わせて更新されるので編集は不要です。

パス	内容
src/asset/team/*/	各チームの紹介ページ用の画像
src/content/alumni/*.yml	卒業生のデータ
src/content/carousel/*.yml	トップページに出るクラスタの定義
src/content/carousel/img/*	トップページに出るクラスタの画像
src/content/member/*.yml	現役メンバーの情報
src/content/member/icons/*	現役メンバーのアイコン
src/news/:year/*.mdx	ニュース記事
src/news/:year/img/*	ニュース記事で使う画像
src/publication/:year/*.yml	出版物
src/team/*.mdx	各チームの紹介ページ
src/team/cover/*	各チーム紹介ページのカバー画像

src/content/alumni/*.yml

プロパティ	意味
year	卒業/退官年度
month	卒業月（type: faculty以外は必要）
name	英語表記での名前
type	faculty, doctor, master, undergraduate

src/content/carousel/*.yml

プロパティ	意味
src	画像ファイルへの相対パス
name	名前

src/content/member/*.yml

プロパティ	意味
name	日本語表記での名前。無くても良い
eng_name	英語表記での名前
occupation	Faculty, Researcher, Student, ResearchStudent
grade	Faculty, Studentの場合は必須。
team	algo, arch, perf, pa, fpga, ss
icon	yamlファイルからの相対パス
username	LDAPに登録されるユーザーネーム
keywords	必須ではない。キーワードのリスト
message	チーム紹介ページに記載されるメッセージ

gradeの詳細は以下。必要に応じて追加するのも可能ですが、 どう修正すればいいかわからない場合はadminないしweb係に相談してください。

grade （Faculty）	説明
Assistant Professor	助教
Associate Professor	准教授
Professor	教授
Professor (Cooperative Gradutate School Program)	連携大学院教授

grade （Student）	説明
D3	D3
D2	D2
D1	D1
M2	M2
M1	M1
B4	B4

src/news/:year/*.mdx

frontmatterのプロパティ	意味
title	タイトル
description	内容の簡潔な説明
date	yyyy-mm-dd形式での発表日
published	公開するかしないか。falseにすると公開されない

Markdownの拡張であるMDXで記述。<h1>は自動で挿入されるので<h2>以下を使うこと。 また、@components/...とすると他のページで使われるコンポーネントも使用可能。 @components/display/Youtube.astroなど。

src/publication/:year/*.yml

プロパティ	説明
title	タイトル
booktitle	学会名、ジャーナル名など
year	発表年
authors	名前のリスト。正規化はされないので英語名でも日本語名でも大丈夫です
bibtex	bibtexのエントリ
reference	plaintextでのリファレンス
class	詳細は下記

class

• journal
• international
  • conference
  • poster
• domestic
  • conference
  • poster
  • workshop
  • magazine
  • misc

現在用意されている分類は上記の通り。 src/content/config.tsの編集で追加は可能ですが、日本語への翻訳があるので少し面倒です。 どう分類するかは過去のファイルを参考にしてください

src/content/team/*.mdx

frontmatterのプロパティ	説明
cover.src	カバー画像への相対パス
cover.alt	カバー画像の代替テキスト
name	チーム名
icon	チームアイコン。iconify-jsonのものが使えます
color	チーム色

| description | チームの簡潔な説明。卒研配属ページなどに表示される | | bachelorInfo.capacities | 受入人数。受け入れ教員と人数を記述する。既存のファイルを参考にすること | | bachelorInfo.informationSessions | 説明会の詳細の配列。詳細は下記別表に |

bachelorInfo.informationSessions

プロパティ	説明
day	yyyy-mm-dd形式での説明会開催日。記述しないと「随時」となる
hour	hh:mm形式での説明会開始時刻と終了時刻。記述しないと「随時」となる
place.display	場所の人間向け文字列。総合研究棟B 1124など
place.canonical	完全な場所の表記。筑波大学 総合研究棟B 1124など
note	オプショナル。特別に記載したいことがある場合は利用する
recentWorks	チーム紹介ページに近年の研究成果として表示したい論文のリスト。論文の詳細はsrc/content/publication以下のものを使うので、src/content/publication以下に追加してからslugで参照する

記述はMDXで行う。@component/...をimport出来るのでそれらを利用して記述する。 recentWorks、カバー画像、メンバー紹介などは自動で追加されるため、 教員ごとの紹介とその他研究室紹介のみを記述する。

インフラ（admin向け）

前段がtraefikでTLS終端を行う。このページ本体のサーブはnginx。 設定ファイルとDockerfileはinfra/に置かれている。

TLS終端はtraefikに集約。/etc/pki/www以下の鍵を使う。 docker-compose.ymlがあるがあくまで参考程度なので、実際にはsystemdで個別にdockerコンテナを動かすので良いと思う。 fallback-httpとfallback-httpsは従来のWebサーバーをDockerコンテナ化したもの。

Design Docs（管理者向け）

フロントエンド

2024年まではWordPressを使いページを作成し、それを静的ページに吐き出すStaticPressプラグインを使ってサイトを構築していた。 しかしStaticPressプラグインの更新が停止しページ更新が不可能になったため、何らかの手段での解決が求められていた。

PHPはメンテナンスコストがかかるため何らかのJavaScriptでのフロントエンドフレームワークへの乗り換えを行うこととした。 ここでフレームワーク選定を行う上での考慮事項は以下の通りである。

• フレームワークの将来性、及び現状での普及度
  • 永遠にメンテナンスし続けることは不可能だが、ある程度は安定して使えることが望ましい。
  • NextはPages RouterからApp Routerへの移行など、安定性にやや不安がある
  • SvelteKitはある程度普及を見せている
  • Qwikは早すぎる
  • Vue系は今後が不安
• 静的ページへの書き出し
  • NodeJSコンテナでサーブし前段のnginxでキャッシュするのは当然考えられるが、 静的ファイルへ書き出せるに越したことはない
  • NextなどのSSR系フレームワークは静的エクスポートはあくまでおまけである
  • いっそRemixに振るのも良いが、基幹系でのコンテナの運用体制が整うまでは静的ファイルで使いたい
  • Astroは静的ファイルを第一においており、かなり有力
• コンテンツ管理
  • yamlファイルで簡単にコンテンツ管理が出来ることが望ましい。Next、Qwikなどでも工夫すれば可能ではあるがやや面倒
  • Headless CMSは自前でホスティングするにせよ外部のものを使うにせよ運用コストがかかる。また移行も面倒になる
  • Astroはsrc/content以下にファイルを置くことで簡易的なコンテンツ管理が可能である。

上記のことを考慮し、Astroを採用した。 動的な部分についてはReactなどは用いずWebComponentsをShadow DOMを使わずに利用する方向とした。 他のSPAフレームワークの導入によるバンドルサイズの増大の抑制と、 必要な学習コストをWeb標準に寄せるのがWebComponents採用の理由である。

Shadow DOMを使っていないのは2024年2月時点ではFirefoxがDeclarative Shadow DOMをサポートしていなかったこと、 AstroのCSSのスコーピング機能と統合することが理由である。

また、CSSフレームワークについても別で導入は行わず、AstroのCSSのスコーピング機能だけを用いた。 TailwindCSSに代表されるユーティリティファーストのCSSフレームワークについては、 そのフレームワークに成熟していなければ読みにくいこと、 デザインシステムが効力を発揮するほどの規模ではないこと、 複雑なセレクタやアニメーションは結局CSSを直接書くしかないことから採用を見送った。

Bootstrapなどのフレームワークについても、デザインから一新するために使用しなかった。

ただしCSS変数は使用している。

インフラ構成

2024年3月時点でのWebサーバーインフラには以下の問題がある

• Apache httpdとの密結合
  • .htaccessが大量に用いられている
  • これによりWebサーバの載せ替えが非常に面倒となっている。設定ファイルも複雑化する
• 単一のWebサーバで全てを行なっている
  • PHPの脆弱性を突かれると巨大な権限が奪われる
  • 部分的なアップデートが困難
  • 責務が分離されておらず、見通しが悪い
• メンテナンスされていないPHPサービス
  • 脆弱性の温床

以上の問題を解決するため、将来的にはReverse Proxy + Dockerコンテナの構成に持っていきたい。 Reverse Proxyは見やすいUIとDockerなどのランタイムとの統合を備えたtraefikを第一候補とし、 PHPサービスは廃止ないしコンテナ単位での分離を目標としていく。 また、.htaccessへの依存をやめて何らかの統一認証基盤を採用することでセキュリティの強化も図る。

全体の更新をいきなり行うのは困難であるため、 まず第一段階としてtraefikの導入と本ページのnginxでのサーブだけを最初に行う。