From 827c121858f6d529cd145addd3028b5e299b9741 Mon Sep 17 00:00:00 2001 From: nlkomaru Date: Thu, 7 Nov 2024 11:20:49 +0900 Subject: [PATCH 1/3] Add backend docs --- .github/workflows/backend-lint.yml | 48 +++++++++++ .github/workflows/build.yml | 4 +- .github/workflows/docs-deploy.yml | 3 +- .../workflows/{lint.yml => front-lint.yml} | 22 ++++- README.md | 11 --- docs/Pipfile | 14 --- docs/docs/backend/config.md | 38 ++++++++ docs/docs/backend/feature.md | 21 +++++ docs/docs/backend/index.md | 27 ++++++ docs/docs/backend/technology-stack.md | 41 +++++++++ docs/docs/frontend/index.md | 0 docs/docs/index.md | 76 +++++++--------- docs/mkdocs.yml | 3 +- docs/start.sh | 6 +- member-portal-backend/Dockerfile | 3 +- .../clients/example_client.json | 6 -- member-portal-backend/cmd/root.go | 2 +- member-portal-backend/config/config.go | 4 +- member-portal-backend/crypto/crypto.go | 9 +- member-portal-backend/crypto/key.go | 15 +++- member-portal-backend/crypto/key_test.go | 2 +- member-portal-backend/db.sqlite3 | Bin 77824 -> 0 bytes member-portal-backend/go.mod | 14 +-- member-portal-backend/go.sum | 32 +++---- member-portal-backend/main.go | 3 +- member-portal-backend/public/assets/kstm.svg | 81 ++++++++++++++++++ .../public/view/authorize.html | 2 +- member-portal-backend/router/root.go | 4 + swagger/README.md | 19 ---- swagger/documentation.yml | 2 - 30 files changed, 366 insertions(+), 146 deletions(-) create mode 100644 .github/workflows/backend-lint.yml rename .github/workflows/{lint.yml => front-lint.yml} (51%) delete mode 100644 docs/Pipfile create mode 100644 docs/docs/backend/config.md create mode 100644 docs/docs/backend/feature.md create mode 100644 docs/docs/backend/index.md create mode 100644 docs/docs/backend/technology-stack.md create mode 100644 docs/docs/frontend/index.md delete mode 100644 member-portal-backend/clients/example_client.json delete mode 100644 member-portal-backend/db.sqlite3 create mode 100644 member-portal-backend/public/assets/kstm.svg delete mode 100644 swagger/README.md diff --git a/.github/workflows/backend-lint.yml b/.github/workflows/backend-lint.yml new file mode 100644 index 0000000..7bb7c5d --- /dev/null +++ b/.github/workflows/backend-lint.yml @@ -0,0 +1,48 @@ +name: Backend Lint + +on: + push: + branches: + - main + pull_request: + paths: + - 'member-portal-backend/**' + +permissions: + statuses: write + contents: read + pull-requests: write + +defaults: + run: + working-directory: member-portal-frontend + +jobs: + golangci: + name: lint + runs-on: ubuntu-latest + steps: + - name: Set commit status as pending + uses: myrotvorets/set-commit-status-action@master + with: + token: ${{ secrets.GITHUB_TOKEN }} + status: pending + context: Check pull request (Backend) + + - uses: actions/checkout@v4 + + - uses: actions/setup-go@v5 + with: + go-version: stable + - name: golangci-lint + uses: golangci/golangci-lint-action@v6 + with: + version: v1.60 + + - name: Set final commit status + uses: myrotvorets/set-commit-status-action@master + if: always() + with: + token: ${{ secrets.GITHUB_TOKEN }} + status: ${{ job.status }} + context: Check pull request (Backend) \ No newline at end of file diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index cfe8f9a..b8a9ad5 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -36,7 +36,7 @@ jobs: platforms: linux/amd64 push: true tags: | - ghcr.io/kstm-su/member-portal/${{ matrix.tag }}:latest - ghcr.io/kstm-su/member-portal/${{ matrix.tag }}:${{ env.GITHUB_SHA_SHORT }} + ghcr.io/${{GITHUB_REPOSITORY_OWNER}}/member-portal/${{ matrix.tag }}:latest + ghcr.io/${{GITHUB_REPOSITORY_OWNER}}/member-portal/${{ matrix.tag }}:${{ env.GITHUB_SHA_SHORT }} cache-from: type=gha,scope=member-portal-${{ matrix.tag }} cache-to: type=gha,mode=max,scope=member-portal-${{ matrix.tag }} diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml index d61a59d..8768a21 100644 --- a/.github/workflows/docs-deploy.yml +++ b/.github/workflows/docs-deploy.yml @@ -29,7 +29,6 @@ jobs: - name: copy swagger run: | - rm -r docs/docs/swagger 2> /dev/null - cp -r -f swagger docs/docs/swagger + cp -r -f ./swagger ./docs/docs/swagger - run: pipenv shell mkdocs gh-deploy --force --config-file ./docs/mkdocs.yml \ No newline at end of file diff --git a/.github/workflows/lint.yml b/.github/workflows/front-lint.yml similarity index 51% rename from .github/workflows/lint.yml rename to .github/workflows/front-lint.yml index c51fbd8..56fd40b 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/front-lint.yml @@ -1,4 +1,4 @@ -name: Check pull request +name: Frontend Lint on: workflow_dispatch: @@ -15,11 +15,17 @@ defaults: run: working-directory: member-portal-frontend - jobs: eslint: runs-on: ubuntu-latest steps: + - name: Set commit status as pending + uses: myrotvorets/set-commit-status-action@master + with: + token: ${{ secrets.GITHUB_TOKEN }} + status: pending + context: Check pull request (Frontend) + - uses: actions/checkout@v4 - uses: actions/setup-node@v4 @@ -33,6 +39,14 @@ jobs: - uses: reviewdog/action-eslint@v1 with: github_token: ${{ secrets.GITHUB_TOKEN }} - reporter: github-pr-review # Change reporter. + reporter: github-pr-review workdir: member-portal-frontend - fail_on_error: 'true' \ No newline at end of file + fail_on_error: 'true' + + - name: Set final commit status + uses: myrotvorets/set-commit-status-action@master + if: always() + with: + token: ${{ secrets.GITHUB_TOKEN }} + status: ${{ job.status }} + context: Check pull request (Frontend) \ No newline at end of file diff --git a/README.md b/README.md index 5d66657..4cebd7b 100644 --- a/README.md +++ b/README.md @@ -19,14 +19,3 @@ kstmメンバーであることを確認し、また事務処理を簡潔化す 4. `http://localhost:3001` にアクセス -## Common - -### APIドキュメント確認方法 -1. `cd swagger`で`swagger`ディレクトリに移動します -2. `npx @redocly/cli preview-docs documentation.yml`を実行します -3. `http://localhost:8080/`にアクセス - -### Mockサーバーの立て方 -1. `swagger/README.md` の "Getting started" の手順を行う -2. "Mock API" の手順を `documentation.yml` と同じディレクトリにて行う -3. `http://localhost:4010`にモックサーバーが立つ \ No newline at end of file diff --git a/docs/Pipfile b/docs/Pipfile deleted file mode 100644 index 8a121dd..0000000 --- a/docs/Pipfile +++ /dev/null @@ -1,14 +0,0 @@ -[[source]] -url = "https://pypi.org/simple" -verify_ssl = true -name = "pypi" - -[packages] -mkdocs-material = "*" - -[dev-packages] - -[scripts] -serve = "mkdocs serve" -build = "mkdocs build" -deploy = "mkdocs gh-deploy" diff --git a/docs/docs/backend/config.md b/docs/docs/backend/config.md new file mode 100644 index 0000000..920ce84 --- /dev/null +++ b/docs/docs/backend/config.md @@ -0,0 +1,38 @@ +# コンフィグの設定について + +```yaml +database: + type: sqlite + sqlite: + path: /app/data/db.sqlite3 +file: + base: /app/data +jwt: + issuer: localhost + key: + private_key: private.pem + public_key: public.pem + key_id: key + realm: localhost +password: + algorithm: argon2 + pepper: #自動で生成されるため、設定不要 +server: + host: localhost + port: 8080 +``` + +## database +postgresqlを利用する場合、以下のように設定を変更してください。 + +```yaml +database: + type: postgres + postgres: + host: db + port: 5432 + user: + password: +``` + + diff --git a/docs/docs/backend/feature.md b/docs/docs/backend/feature.md new file mode 100644 index 0000000..deec212 --- /dev/null +++ b/docs/docs/backend/feature.md @@ -0,0 +1,21 @@ +# 実装機能 + +- [x] OAuth2認可 + - [x] 認可コード取得 + - [x] アクセストークン取得 + - [x] リフレッシュトークン取得 + - [ ] トークン削除 + - [ ] トークン情報取得 + - [ ] トークン有効性確認 + - [ ] クライアント作成 +- [ ] OpenID Connect認証 + - [x] クライアント情報取得 + - [ ] ユーザー情報取得 + - [ ] ユーザー情報更新 +- [ ] ユーザー情報取得API + - [x] プロフィール取得(OIDC クライアント情報取得と同一) + - [ ] ユーザー情報更新 + - [ ] 新規ユーザー登録 + - [ ] ユーザーリスト取得 + - [ ] お知らせ取得 + - [ ] お知らせ更新 \ No newline at end of file diff --git a/docs/docs/backend/index.md b/docs/docs/backend/index.md new file mode 100644 index 0000000..aaaa290 --- /dev/null +++ b/docs/docs/backend/index.md @@ -0,0 +1,27 @@ +# バックエンドについて + +## バックエンドの概要 + +バックエンドはGo言語で実装されています。 +OAuth2およびOpenID Connectを使用して認可・認証を行い、ユーザー情報を渡すAPIを提供します。 + +## 起動方法 + +### Dockerでの起動方法 +#### Localでビルドする場合 + +1. Dockerfileのあるディレクトリに移動 +2. `docker build -t .` を実行（image_nameは自由に設定） +3. `docker run -p 3001:8080 -d ` を実行 +4. `http://localhost:3001` にアクセス + +#### GitHub container registryからpullする場合 +1. `docker pull ghcr.io/kstm-su/member-portal/backend:latest` を実行 +2. `docker run -p 3001:8080 -d ghcr.io/kstm-su/member-portal/backend:latest` を実行 +3. `http://localhost:3001` にアクセス + +### Goでローカルで起動する場合 +1. `cd member-portal-backend` でディレクトリに移動 +2. `go run main.go` を実行 +3. `http://localhost:8080` にアクセス + diff --git a/docs/docs/backend/technology-stack.md b/docs/docs/backend/technology-stack.md new file mode 100644 index 0000000..4800331 --- /dev/null +++ b/docs/docs/backend/technology-stack.md @@ -0,0 +1,41 @@ +# 技術スタック + +## 採用ライブラリ + +Web framework: [echo](https://echo.labstack.com/)
+採用理由: openapi-generatorを利用することを想定し、親和性の高いechoを採用。 + +ORM: [gorm](https://gorm.io/)
+採用理由: GitHubのスター数が多く、開発者が多いため。 + +Command line tool: [cobra](https://cobra.dev/)
+採用理由: サブコマンドの実装が容易であるため また、k8sでも採用されているため、 + +Config: [viper](https://github.com/spf13/viper)
+採用理由: cli toolとして採用した、cobraとの親和性が高いため、 + +## 依存ソフトウェア + +Language: [Go](https://golang.org/)
+採用理由: 本プロジェクトの言語として採用。 + +Linter & Formatter: [golangci-lint](https://golangci-lint.run/)
+採用理由: GitHubのスター数が多く、開発者が多いため。また、複数のlinterを統合しているため。 + +Database: [PostgreSQL](https://www.postgresql.org/) [Optional]
+採用理由: 慣習的に利用されるため。 また、ORMのgormが対応しているため。 (ConfigでSQLite3を利用することも可能) + +Secret Manager(検討中): [Hashicorp Vault](https://www.vaultproject.io/)　
+採用理由: シークレット管理のため
+利用場面: パスワードハッシュ化時のpepperの管理および、OAuth2クライアントのシークレット管理の際に利用のため。
+その他の候補: [Cyber Ark conjur](https://www.conjur.org/), [Infisical](https://infisical.com/) + +Object storage: [MinIO](https://min.io/) [Optional]
+採用理由: S3互換のため。 + + + + + + + diff --git a/docs/docs/frontend/index.md b/docs/docs/frontend/index.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/index.md b/docs/docs/index.md index e8325b3..08ef96c 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -1,46 +1,36 @@ +title: Home + # Member portalとは kstmメンバーであることを確認し、また事務処理を簡潔化するためのポータルサイトです。 -## Common -### Redoc(OpenAPI)にアクセスするには -[Redoc](redoc) - -## Frontend -### Dockerでの起動方法 -#### Localでビルドする場合 -1. Dockerfileのあるディレクトリに移動 -2. `docker build -t .` を実行（image_nameは自由に設定） -3. `docker run -p 3000:3000 -d ` を実行 -4. `http://localhost:3000` にアクセス - -#### GitHub container registryからpullする場合 -1. `docker pull ghcr.io/kstm-su/member-portal/frontend:latest` を実行 -2. `docker run -p 3000:3000 -d ghcr.io/kstm-su/member-portal/frontend:latest` を実行 -3. `http://localhost:3000` にアクセス - -### Nodeでローカルで起動する場合 -1. `cd member-portal-frontend` でディレクトリに移動 -2. `npm install` を実行 -3. `npm run dev` を実行 -4. `http://localhost:3000` にアクセス - - -## Backend - -### Dockerでの起動方法 -#### Localでビルドする場合 - -1. Dockerfileのあるディレクトリに移動 -2. `docker build -t .` を実行（image_nameは自由に設定） -3. `docker run -p 3001:8080 -d ` を実行 -4. `http://localhost:3001` にアクセス - -#### GitHub container registryからpullする場合 -1. `docker pull ghcr.io/kstm-su/member-portal/backend:latest` を実行 -2. `docker run -p 3001:8080 -d ghcr.io/kstm-su/member-portal/backend:latest` を実行 -3. `http://localhost:3001` にアクセス - -### Goでローカルで起動する場合 -1. `cd member-portal-backend` でディレクトリに移動 -2. `go run main.go` を実行 -3. `http://localhost:8080` にアクセス +## APIエンドポイントについて + +### APIドキュメント確認方法 + +#### Github Pagesで確認する方法 +masterブランチのAPIドキュメントについては[こちら](redoc/index.html)で確認できます。 + +#### ローカルで確認する方法 +1. `cd swagger`で`swagger`ディレクトリに移動します +2. `npx @redocly/cli preview-docs documentation.yml`を実行します +3. `http://localhost:8080/`にアクセス + +### Mockサーバーの立て方 +#### Mockサーバーとは + +APIのエンドポイントを実際に立てずに、APIのレスポンスをモックで返すサーバーのことです。 + +#### 立て方 +1. `swagger/README.md` の "Getting started" の手順を行う +2. "Mock API" の手順を `documentation.yml` と同じディレクトリにて行う +3. `http://localhost:4010`にモックサーバーが立つ + +## 依存ソフトウェア + +API Docmentation: [redocly cli](https://redocly.com/docs/cli)
+採用理由 : openapi形式のドキュメントを生成するため、swagger +利用場面: apiのドキュメント生成および表示 + +Container runtime: [Docker](https://www.docker.com/)
+採用理由: 事実上のデファクトスタンダードであるため + diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 4f040cb..e4e9cff 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -27,7 +27,8 @@ markdown_extensions: anchor_linenums: true - pymdownx.inlinehilite - pymdownx.superfences - + - pymdownx.tasklist: + custom_checkbox: true plugins: - search: lang: ja diff --git a/docs/start.sh b/docs/start.sh index c8d3dc9..10817ce 100644 --- a/docs/start.sh +++ b/docs/start.sh @@ -1,3 +1,3 @@ -rm -r docs/swagger 2> /dev/null -cp -r -f ../swagger docs/swagger -pipenv shell mkdocs serve +rm -r ./docs/swagger 2> /dev/null +cp -r -f ../swagger ./docs/swagger +mkdocs serve diff --git a/member-portal-backend/Dockerfile b/member-portal-backend/Dockerfile index bc92ebe..9f3bca2 100644 --- a/member-portal-backend/Dockerfile +++ b/member-portal-backend/Dockerfile @@ -1,4 +1,4 @@ -FROM --platform=$BUILDPLATFORM golang:1.22.4 as build +FROM --platform=$BUILDPLATFORM golang:1.22.4 AS build RUN mkdir /storage WORKDIR /go/src/github.com/kstm-su/Member-Portal/backend/ @@ -26,7 +26,6 @@ WORKDIR /app EXPOSE 8080 COPY --from=build /storage/ /app/storage/ -VOLUME /app/storage COPY --from=build /go/src/github.com/kstm-su/Member-Portal/backend/public /app/public diff --git a/member-portal-backend/clients/example_client.json b/member-portal-backend/clients/example_client.json deleted file mode 100644 index 4553a4e..0000000 --- a/member-portal-backend/clients/example_client.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "clientId": "example_client", - "clientName": "Example Client", - "redirectUri": "http://localhost:3000/callback", - "applicationName": "Example Application" -} diff --git a/member-portal-backend/cmd/root.go b/member-portal-backend/cmd/root.go index 3ab3f94..3d03b69 100644 --- a/member-portal-backend/cmd/root.go +++ b/member-portal-backend/cmd/root.go @@ -21,7 +21,7 @@ func init() { // コマンドフラグの設定 flags := rootCmd.PersistentFlags() // 設定ファイルのパスを指定するフラグ --config, -c - flags.StringVarP(&configFile, "config", "c", "/app/config.yaml", "config file path (default is /app/config.yaml)") + flags.StringVarP(&configFile, "config", "c", "/app/data/config.yaml", "config file path (default is /app/data/config.yaml)") } func Execute() error { diff --git a/member-portal-backend/config/config.go b/member-portal-backend/config/config.go index effafa7..2da676f 100644 --- a/member-portal-backend/config/config.go +++ b/member-portal-backend/config/config.go @@ -54,11 +54,11 @@ func init() { viper.SetDefault("server.port", 8080) viper.SetDefault("server.host", "localhost") - viper.SetDefault("file.base", "/app") + viper.SetDefault("file.base", "/app/data") viper.SetDefault("database.type", "sqlite") - viper.SetDefault("database.sqlite.path", "/app/db.sqlite3") + viper.SetDefault("database.sqlite.path", "/app/data/db.sqlite3") viper.SetDefault("jwt.key.private_key", "private.pem") viper.SetDefault("jwt.key.public_key", "public.pem") diff --git a/member-portal-backend/crypto/crypto.go b/member-portal-backend/crypto/crypto.go index 2ecec46..525e84d 100644 --- a/member-portal-backend/crypto/crypto.go +++ b/member-portal-backend/crypto/crypto.go @@ -73,6 +73,9 @@ func VerifyPassword(hash string, password string, config config.Config) bool { var threads uint8 _, err = fmt.Sscanf(parts[3], "m=%d,t=%d,p=%d", &memory, &iterator, &threads) + if err != nil { + panic(err.Error()) + } // ハッシュ値の長さを取得 keyLen := len(decodedHash) @@ -83,11 +86,7 @@ func VerifyPassword(hash string, password string, config config.Config) bool { genHash := argon2.IDKey([]byte(withPepper), salt, uint32(iterator), memory, threads, uint32(keyLen)) // 生成したハッシュ値とデータベースに保存されているハッシュ値を比較 - if bytes.Equal(decodedHash, genHash) { - return true - } - - return false + return bytes.Equal(decodedHash, genHash) } func GenerateRandomString(n int) string { diff --git a/member-portal-backend/crypto/key.go b/member-portal-backend/crypto/key.go index c500d1c..76af445 100644 --- a/member-portal-backend/crypto/key.go +++ b/member-portal-backend/crypto/key.go @@ -33,6 +33,9 @@ func Init(config config.Config) { slog.Info("キーペアより証明書を取得します") keys := GetKeys(config) err = generateCertificate(keys.PrivateKey, keys.PublicKey) + if err != nil { + panic("証明書の取得に失敗しました") + } slog.Info("証明書の取得が完了しました") slog.Info("jwks.jsonを生成します") @@ -148,7 +151,7 @@ func generateCertificate(privateKey *rsa.PrivateKey, publicKey *rsa.PublicKey) e defer func(certFile *os.File) { err := certFile.Close() if err != nil { - + panic("証明書の書き込みに失敗しました") } }(certFile) @@ -172,12 +175,12 @@ func generateJWKs(config config.Config) { //そうでない場合 file, err := os.Create(jwksFile) if err != nil { - slog.Warn("jwks.jsonの生成に失敗しました: %v", err) + slog.Warn("jwks.jsonの生成に失敗しました") } defer func(file *os.File) { err := file.Close() if err != nil { - + panic("jwks.jsonの書き込みに失敗しました") } }(file) @@ -185,7 +188,7 @@ func generateJWKs(config config.Config) { key, err := jwk.PublicKeyOf(privateKey) if err != nil { - slog.Warn("jwksのpublickey生成に失敗しました: %v", err) + slog.Warn("jwksのpublickey生成に失敗しました") } uniqueId := uuid.New() @@ -205,6 +208,10 @@ func generateJWKs(config config.Config) { // Save the JWK set to a file _, err = file.Write(encoded) + if err != nil { + slog.Warn("jwks.jsonの生成に失敗しました") + return + } } func GetKeys(config config.Config) Key { diff --git a/member-portal-backend/crypto/key_test.go b/member-portal-backend/crypto/key_test.go index 6c6c3a2..55c40bc 100644 --- a/member-portal-backend/crypto/key_test.go +++ b/member-portal-backend/crypto/key_test.go @@ -9,7 +9,7 @@ import ( func TestGenKey(t *testing.T) { var cfg = config.Config{} cfg.File.Base = "/tmp" - err := GenKey(2048, cfg) + err := genKey(cfg) if err != nil { t.Errorf("GenKey failed, expected nil, got %v", err) } diff --git a/member-portal-backend/db.sqlite3 b/member-portal-backend/db.sqlite3 deleted file mode 100644 index ff2a6b8be8b7cf6f0844c7cef46a7b69878da92d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 77824 zcmeI%%~IP|6u@ySAvOk#328?w25o52z$9^-nQYRTQdh|^Nla>-1=EErY}r<0TaF}? zWNEtUGi1?jyXc#=Z_o$nviDvikN}Zg7n;9ktdFa&bAIPuf6P7n@ue5JM$ZpMPGo#j zSSx5+;XA`96bfbWz9-)COYSekJ7TRRwzD?Ng$F0UR;vFN))#LVsz=qoSAVNMsQkGa zt^8AomOrihvGn`$&*i_CrsXfnpBCSUlXxM300IagfWZGD@Or(d@9bztk#jtB!*@gR zd%zCecT;!Vxx9O?-n8~wmeJb#{-tGHI(K{QjNDyur8#?gx1`^{ubntMej?()iNw07Im z&<$*P?uiq022Qa3^&@ll;x1h$a@$7aeu$EdZrBODN#yzC`7v|0P%Y^j8`|tA75*gf zd!CSq*K6sZ<7OG}_0K;$!}dl_|NQyKo_`ifGM|fEnC8Q^qF&$73f{QuemJvsrjf7q z?f9{FE#A62`>ImXbzM8%QE|(1gle&xj##y2huialFtX)ImmG)A_3b0C+a0=>u6Qiu zvobSRi~6^ER%R+ZyQWsv+4E&pi&IDC)bYoW=p|viUP)&bH)kgob_TvbwB3>84dbp5 zPLI2L4#2JRKdoL7FKm>4z&fl{1dquEkrG)8%qW z-`v!GaaHO)r!yT!o*SNTETxk_Zf3cEP7saU@paWtrxo8tfS9}W zgT`U2xwqeF8SUO%+v$nn;yH3ah4$HrZR6QN)7pRDP@^^#o@q3#XI9f{)U89KoxHf6 z91XRlqHb+w^_lr&1dd%h-&~%3St{vUTiR@-0F$>)ZZD=8lZUeVQ34?TVA^f>1E(tn z&DjT4X7_)xSkzx^Wu=mQzFkZ1m1jTPnGf*3N+|Hfr;=I}(7t$H4 zw(M#RoN(ZF?THhH@5R8r7_hZR@(Usk{Iiua7jBAN1tCf%Q8z z;HoV<@Uho<`?*TRUpl5~-nuC~^(echR`P%LqWp1Dk&89C;DrDJ2q1s}0tg_000Iag zfB*t{6U=V#$<>90tg_000Iag zfB*srAb コンフィグ -> ルーター err := cmd.Execute() if err != nil { - err.Error() + slog.Warn(err.Error()) return } } diff --git a/member-portal-backend/public/assets/kstm.svg b/member-portal-backend/public/assets/kstm.svg new file mode 100644 index 0000000..fb0ccec --- /dev/null +++ b/member-portal-backend/public/assets/kstm.svg @@ -0,0 +1,81 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/member-portal-backend/public/view/authorize.html b/member-portal-backend/public/view/authorize.html index dbc0cf6..708816a 100644 --- a/member-portal-backend/public/view/authorize.html +++ b/member-portal-backend/public/view/authorize.html @@ -20,7 +20,7 @@

> logo diff --git a/member-portal-backend/router/root.go b/member-portal-backend/router/root.go index d47846f..5214cab 100644 --- a/member-portal-backend/router/root.go +++ b/member-portal-backend/router/root.go @@ -43,6 +43,10 @@ func Execute(c *config.Config) { //e.GET("/.well-known/openid-configuration", OpenIDConfigurationHandler) e.GET("/.well-known/jwks.json", JWKsHandler) + e.GET("/assets/*", func(c echo.Context) error { + return c.File("public/assets/" + c.Param("*")) + }) + //サーバーの起動 var port = c.Server.Port e.Logger.Fatal(e.Start(":" + strconv.Itoa(port))) diff --git a/swagger/README.md b/swagger/README.md deleted file mode 100644 index e82f1f1..0000000 --- a/swagger/README.md +++ /dev/null @@ -1,19 +0,0 @@ -# OpenAPI documentation - -## Getting started - -```bash -npm install -g @stoplight/prism-cli -``` - -## Generate API documentation - -```bash -npx @redocly/cli preview-docs documentation.yml -``` - -## Mock API - -```bash -prism mock documentation.yml -``` \ No newline at end of file diff --git a/swagger/documentation.yml b/swagger/documentation.yml index 3c235b9..d298dac 100644 --- a/swagger/documentation.yml +++ b/swagger/documentation.yml @@ -26,8 +26,6 @@ components: scopes: openid: Grants read access for OpenID Connect profile: Grants read access for my profile - write: Grants write access for all - read: Grants read access for all paths: /oauth2/userinfo: From d7e64dd6ac8967d63fbb172b3817bedec8692a9a Mon Sep 17 00:00:00 2001 From: nlkomaru Date: Thu, 7 Nov 2024 11:40:49 +0900 Subject: [PATCH 2/3] Add frontend docs --- .github/workflows/backend-lint.yml | 2 +- README.md | 15 -------------- docs/docs/frontend/index.md | 27 ++++++++++++++++++++++++++ docs/docs/frontend/technology-stack.md | 25 ++++++++++++++++++++++++ 4 files changed, 53 insertions(+), 16 deletions(-) create mode 100644 docs/docs/frontend/technology-stack.md diff --git a/.github/workflows/backend-lint.yml b/.github/workflows/backend-lint.yml index 7bb7c5d..5b6402c 100644 --- a/.github/workflows/backend-lint.yml +++ b/.github/workflows/backend-lint.yml @@ -15,7 +15,7 @@ permissions: defaults: run: - working-directory: member-portal-frontend + working-directory: member-portal-backend jobs: golangci: diff --git a/README.md b/README.md index 4cebd7b..cd01d74 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,6 @@ # member-portal kstmメンバーであることを確認し、また事務処理を簡潔化するためのポータルサイト -## Frontend -### Docker起動方法 -1. Dockerfileのあるディレクトリに移動 -2. `docker build -t .` を実行（image_nameは自由に設定） -3. `docker run -p 3000:3000 -d ` を実行 -4. `http://localhost:3000` にアクセス -※ ローカルで起動する場合は、`npm run dev` を実行 - -## Backend - -### Docker起動方法 -1. Dockerfileのあるディレクトリに移動 -2. `docker build -t .` を実行（image_nameは自由に設定） -3. `docker run -p 3001:8080 -d ` を実行 -4. `http://localhost:3001` にアクセス diff --git a/docs/docs/frontend/index.md b/docs/docs/frontend/index.md index e69de29..028f4a3 100644 --- a/docs/docs/frontend/index.md +++ b/docs/docs/frontend/index.md @@ -0,0 +1,27 @@ +# フロントエンドについて + +## フロントエンドの概要 + +Next.jsを使用し、backendと連携して動作するフロントエンドです。 +メンバーの管理および、メンバーの情報を表示するためのページを提供します。 + +## 起動方法 + +### Dockerでの起動方法 +#### Localでビルドする場合 + +1. Dockerfileのあるディレクトリに移動 +2. `docker build -t .` を実行（image_nameは自由に設定） +3. `docker run -p 3000:3000 -d ` を実行 +4. `http://localhost:3000` にアクセス + +#### GitHub container registryからpullする場合 +1. `docker pull ghcr.io/kstm-su/member-portal/frontend:latest` を実行 +2. `docker run -p 3000:3000 -d ghcr.io/kstm-su/member-portal/frontend:latest` を実行 +3. `http://localhost:3000` にアクセス + +### Nodeでローカルで起動する場合 +1. `cd member-portal-frontend` でディレクトリに移動 +2. `npm run dev` を実行 +3. `http://localhost:3000` にアクセス + diff --git a/docs/docs/frontend/technology-stack.md b/docs/docs/frontend/technology-stack.md new file mode 100644 index 0000000..ff5fb36 --- /dev/null +++ b/docs/docs/frontend/technology-stack.md @@ -0,0 +1,25 @@ +# 技術スタック + +## 採用ライブラリ + +Web framework: [Next.js](https://nextjs.org/)
+採用理由: Reactのフレームワークとして幅広く利用されているため。 + +UI framework: [shadcn](https://ui.shadcn.com/)
+採用理由: Headless UIであるradix-uiを利用しており、styleについてtailwindcssを利用しているため。 + +## 依存ソフトウェア + +Language: [Typescript](https://www.typescriptlang.org/)
+採用理由: 本プロジェクトの言語として採用。 + +Runtime: [Node.js](https://nodejs.org/)
+採用理由: Next.jsの開発環境として採用されているため。 + +Linter : [eslint](https://eslint.org/)
+採用理由: コードの品質を保つため。また、Next.jsのデフォルトの設定として採用されているため。 + + + + + From cc88a1822ed38e8deed5106b3fd18ea2e4ca667b Mon Sep 17 00:00:00 2001 From: nlkomaru Date: Thu, 7 Nov 2024 12:47:31 +0900 Subject: [PATCH 3/3] Add common docs --- .github/workflows/backend-lint.yml | 5 ++-- .github/workflows/docs-deploy.yml | 16 +++-------- .gitignore | 5 +++- README.md | 31 +++++++++++++++++++++ docs/docs/common/about-this.md | 43 ++++++++++++++++++++++++++++++ docs/docs/common/api-docs.md | 24 +++++++++++++++++ docs/docs/index.md | 10 ++----- docs/mkdocs.yml | 15 +++++++++++ 8 files changed, 125 insertions(+), 24 deletions(-) create mode 100644 docs/docs/common/about-this.md create mode 100644 docs/docs/common/api-docs.md diff --git a/.github/workflows/backend-lint.yml b/.github/workflows/backend-lint.yml index 5b6402c..4de9ec3 100644 --- a/.github/workflows/backend-lint.yml +++ b/.github/workflows/backend-lint.yml @@ -13,9 +13,6 @@ permissions: contents: read pull-requests: write -defaults: - run: - working-directory: member-portal-backend jobs: golangci: @@ -34,9 +31,11 @@ jobs: - uses: actions/setup-go@v5 with: go-version: stable + - name: golangci-lint uses: golangci/golangci-lint-action@v6 with: + working-directory: member-portal-backend version: v1.60 - name: Set final commit status diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml index 8768a21..24476c5 100644 --- a/.github/workflows/docs-deploy.yml +++ b/.github/workflows/docs-deploy.yml @@ -15,20 +15,12 @@ jobs: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: - python-version: "3.12" - - name: install pipenv - run: | - python -m pip install --upgrade pip - python -m pip install pipenv - - - name: lock package version - run: pipenv lock - - - name: install packages - run: pipenv sync --dev + python-version: 3.12 + - run: | + pip install mkdocs-material - name: copy swagger run: | cp -r -f ./swagger ./docs/docs/swagger - - run: pipenv shell mkdocs gh-deploy --force --config-file ./docs/mkdocs.yml \ No newline at end of file + - run: mkdocs gh-deploy --config-file ./docs/mkdocs.yml \ No newline at end of file diff --git a/.gitignore b/.gitignore index 6879dab..40347e7 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,7 @@ docs/docs/swagger docs/site -.idea \ No newline at end of file +.idea + +member-portal-backend/app/** +member-portal-backend/app-local/** \ No newline at end of file diff --git a/README.md b/README.md index cd01d74..bb8b605 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,37 @@ # member-portal kstmメンバーであることを確認し、また事務処理を簡潔化するためのポータルサイト +[Wiki](https://kstm-su.github.io/member-portal/) + +## Frontend +### Docker起動方法 +1. Dockerfileのあるディレクトリに移動 +2. `docker build -t .` を実行（image_nameは自由に設定） +3. `docker run -p 3000:3000 -d ` を実行 +4. `http://localhost:3000` にアクセス + +※ ローカルで起動する場合は、`npm run dev` を実行 + +## Backend + +### Docker起動方法 +1. Dockerfileのあるディレクトリに移動 +2. `docker build -t .` を実行（image_nameは自由に設定） +3. `docker run -p 3001:8080 -d ` を実行 +4. `http://localhost:3001` にアクセス + + +## Common + +### APIドキュメント確認方法 +1. `cd swagger`で`swagger`ディレクトリに移動します +2. `npx @redocly/cli preview-docs documentation.yml`を実行します +3. `http://localhost:8080/`にアクセス + +### Mockサーバーの立て方 +1. `swagger/README.md` の "Getting started" の手順を行う +2. "Mock API" の手順を `documentation.yml` と同じディレクトリにて行う +3. `http://localhost:4010`にモックサーバーが立つ diff --git a/docs/docs/common/about-this.md b/docs/docs/common/about-this.md new file mode 100644 index 0000000..2847465 --- /dev/null +++ b/docs/docs/common/about-this.md @@ -0,0 +1,43 @@ +# 当ドキュメントについて + +このドキュメントは、[MkDocs-material](https://squidfunk.github.io/mkdocs-material/)を使用して作成されました。 + +## 目的 + +今後の開発の参入障壁を低くするために、どのような技術スタックを利用し、何を目的としているかを示すため。 + +## 編集するには +`docs/docs`にドキュメントの本体が配置されているため、そちらを編集してください。
+また、新たにファイルを追加する場合は、`mkdocs.yml`にある`nav`に追加してください。 + +## 表示方法 + +### ローカルでの表示 + +以下のコマンドを実行することで、ローカルでの表示が可能です。 + +#### 事前準備 + +```bash +pip install mkdocs-material +``` + +#### Linux + +```bash +cd docs +./start.sh +``` + +#### Windows + +`docs/docs`に`swagger`をコピーしたのち、以下のコマンドを実行してください。 + +```bash +cd docs +mkdocs serve +``` + +### GitHub Pagesでの表示 + +GitHub Pagesでの表示は、[こちら](https://kstm-su.github.io/member-portal/)からご覧いただけます。 \ No newline at end of file diff --git a/docs/docs/common/api-docs.md b/docs/docs/common/api-docs.md new file mode 100644 index 0000000..df97d28 --- /dev/null +++ b/docs/docs/common/api-docs.md @@ -0,0 +1,24 @@ +# APIドキュメントについて + +## 目的 +OpenAPIを利用してAPIドキュメントを作成することで、フロントエンドとバックエンドの実装を隠蔽し、APIの定義をインターフェースとして利用することにより、開発効率を向上させる。 + +## 仕様 +- OpenAPI 3.0.0 +- ファイル形式: YAML +- ファイル名: documentation.yaml +- ファイルの配置場所: /swagger + +## ファイル構成 +`/components`: OpenAPIのコンポーネントを定義する
+`/paths`: APIのエンドポイントを定義する
+`documentation.yaml`: OpenAPIの定義を記述するファイル + +## APIドキュメントの確認方法 +### Github Pagesで確認する方法 +masterブランチのAPIドキュメントについては[こちら](/member-portal/redoc/index.html)で確認できます。 + +### ローカルで確認する方法 +1. `cd swagger`で`swagger`ディレクトリに移動します +2. `npx @redocly/cli preview-docs documentation.yml`を実行します +3. `http://localhost:8080/`にアクセス \ No newline at end of file diff --git a/docs/docs/index.md b/docs/docs/index.md index 08ef96c..9f4e8e1 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -7,13 +7,7 @@ kstmメンバーであることを確認し、また事務処理を簡潔化す ### APIドキュメント確認方法 -#### Github Pagesで確認する方法 -masterブランチのAPIドキュメントについては[こちら](redoc/index.html)で確認できます。 -#### ローカルで確認する方法 -1. `cd swagger`で`swagger`ディレクトリに移動します -2. `npx @redocly/cli preview-docs documentation.yml`を実行します -3. `http://localhost:8080/`にアクセス ### Mockサーバーの立て方 #### Mockサーバーとは @@ -28,9 +22,9 @@ APIのエンドポイントを実際に立てずに、APIのレスポンスを ## 依存ソフトウェア API Docmentation: [redocly cli](https://redocly.com/docs/cli)
-採用理由 : openapi形式のドキュメントを生成するため、swagger +採用理由 : openapi形式のドキュメントを生成および表示するため。
利用場面: apiのドキュメント生成および表示 Container runtime: [Docker](https://www.docker.com/)
-採用理由: 事実上のデファクトスタンダードであるため +採用理由: 事実上のデファクトスタンダードであるため。 diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index e4e9cff..8f7874b 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -29,6 +29,21 @@ markdown_extensions: - pymdownx.superfences - pymdownx.tasklist: custom_checkbox: true +nav: + - Home: + - 初めに: index.md + - Backend: + - セットアップ: backend/index.md + - 実装機能: backend/feature.md + - コンフィグ: backend/config.md + - 技術スタック: backend/technology-stack.md + - Frontend: + - セットアップ: frontend/index.md + - 技術スタック: frontend/technology-stack.md + - Common: + - APIドキュメント: common/api-docs.md + - 当ドキュメントについて: common/about-this.md + - Redocly: redoc/index.html plugins: - search: lang: ja