Merge pull request #2 from SageSeekerSociety/feat-init

feat: init

.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: 'maven'
+    directory: '/'
+    schedule:
+      interval: 'monthly'
+
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'monthly'
+
+  - package-ecosystem: 'docker'
+    directory: '/'
+    schedule:
+      interval: 'monthly'
+
+  - package-ecosystem: 'devcontainers'
+    directory: '/'
+    schedule:
+      interval: 'monthly'

.github/workflows/build.yml

@@ -0,0 +1,68 @@
+name: Build
+
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    services:
+      # See: https://docs.github.com/en/actions/using-containerized-services/creating-postgresql-service-containers
+      # Label used to access the service container
+      postgres:
+        # Docker Hub image
+        image: postgres:latest
+        # Provide the password for postgres
+        env:
+          POSTGRES_PASSWORD: postgres
+        # Set health checks to wait until postgres has started
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+          --name my_postgres_container
+        ports:
+          # Maps tcp port 5432 on service container to the host
+          - 5432:5432
+      elasticsearch: # See: https://discuss.elastic.co/t/set-password-and-user-with-docker-compose/225075
+        image: docker.elastic.co/elasticsearch/elasticsearch:8.12.2
+        env:
+          discovery.type: single-node
+          xpack.security.enabled: true
+          ELASTIC_USERNAME: elastic
+          ELASTIC_PASSWORD: elastic
+        options: >-
+          --health-cmd "curl http://localhost:9200/_cluster/health"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+        ports:
+          # Maps tcp port 9200 on service container to the host
+          - 9200:9200
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+          cache: 'maven'
+          settings-path: ${{ github.workspace }} # location for the settings.xml file
+
+      - name: Build with Maven
+        run: mvn install
+
+      - name: Upload jar
+        uses: actions/upload-artifact@v4
+        with:
+          name: jar
+          path: target/*.jar
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: target/site/jacoco

.github/workflows/code-ql.yml

@@ -0,0 +1,143 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL"
+
+on:
+  push:
+  pull_request:
+    branches: [ "main", "dev" ]
+  merge_group:
+  schedule:
+    - cron: '0 0 * * *'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    timeout-minutes: ${{ (matrix.language == 'swift' && 120) || 360 }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: java-kotlin
+            build-mode: manual
+        # CodeQL supports the following values keywords for 'language': 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Initializes the CodeQL tools for scanning.
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+          # If you wish to specify custom queries, you can do so here or in a config file.
+          # By default, queries listed here will override any specified in a config file.
+          # Prefix the list here with "+" to use these queries and those in the config file.
+
+          # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+          # queries: security-extended,security-and-quality
+
+      # If the analyze step fails for one of the languages you are analyzing with
+      # "We were unable to automatically build your code", modify the matrix above
+      # to set the build mode to "manual" for that language. Then modify this step
+      # to build your code.
+      # ℹ️ Command-line programs to run using the OS shell.
+      # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+      - if: matrix.build-mode == 'manual'
+        shell: bash
+        run: |
+          ./mvnw compile
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{matrix.language}}"
+
+  # A workaround for Github Merge Queue
+  # See:
+  #   https://github.com/coveo/platform-client/pull/819
+  #   https://github.com/github/codeql-action/issues/1537
+  #   https://github.com/github/codeql-action/issues/1572
+
+  # The CodeQL action status is not reported in merge queues. See https://github.com/github/codeql-action/issues/1537.
+  # This is a workaround to check the status of the CodeQL analysis in the PR but not in the merge queue. See https://github.com/orgs/community/discussions/46757#discussioncomment-7768838
+  check_codeql_status:
+    name: Check CodeQL Status
+    needs: analyze
+    permissions:
+      contents: read
+      checks: read
+      pull-requests: read
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'pull_request' }}
+    steps:
+      - name: Authenticate gh CLI
+        run: |
+          gh auth login --with-token <<< "${{ secrets.GITHUB_TOKEN }}"
+      - name: Check CodeQL Status
+        run: |
+          response=$(gh api graphql -f query='
+            {
+              repository(owner: "${{ github.event.repository.owner.login }}", name: "${{ github.event.repository.name }}") {
+                pullRequest(number: ${{ github.event.pull_request.number }}) {
+                  commits(last: 1) {
+                    nodes {
+                      commit {
+                        checkSuites(first: 1, filterBy: {checkName: "CodeQL"}) {
+                          nodes {
+                            checkRuns(first: 1) {
+                              nodes {
+                                name
+                                status
+                                conclusion
+                              }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          ')
+          conclusion=$(echo $response | jq -r '.data.repository.pullRequest.commits.nodes[0].commit.checkSuites.nodes[0].checkRuns.nodes[0].conclusion')
+            if [ "$conclusion" != "SUCCESS" ]; then
+              echo "$response"
+              echo "CodeQL check failed"
+              exit 1
+            fi

.gitignore

@@ -0,0 +1,32 @@
+target/
+!.mvn/wrapper/maven-wrapper.jar
+!**/src/main/**/target/
+!**/src/test/**/target/
+
+### STS ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+
+### IntelliJ IDEA ###
+.idea
+*.iws
+*.iml
+*.ipr
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+build/
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+### VS Code ###
+.vscode/

.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,19 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+wrapperVersion=3.3.2
+distributionType=only-script
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.7/apache-maven-3.9.7-bin.zip

README.md

@@ -1,2 +1,68 @@
 # cheese-backend-nt
-Yet another backend for cheese.
+Welcome to the cheese-backend-nt project!
+
+## Environment
+You need to set up several things before you can compile and run this project.
+
+### Prerequisites
+To get started, you need to install JDK 21. Make sure you have the correct version by running ```java -version``` and
+```javac -version```. Incorrect version will result in all sorts of errors.
+
+You also need to set up PostgreSQL and ElasticSearch. We recommend using Docker to run these services. Run the following
+scripts in Unix shell or the bash in Docker Desktop to start the services:
+```bash
+#!/bin/sh
+sudo systemctl start docker.service
+
+sudo docker run -d \
+    --name elasticsearch \
+    -e discovery.type=single-node \
+    -e xpack.security.enabled=true \
+    -e ELASTIC_USERNAME=elastic \
+    -e ELASTIC_PASSWORD=elastic \
+    --health-cmd="curl http://localhost:9200/_cluster/health" \
+    --health-interval=10s \
+    --health-timeout=5s \
+    --health-retries=10 \
+    -p 9200:9200 \
+    docker.elastic.co/elasticsearch/elasticsearch:8.12.1
+
+sudo docker run -d \
+    --name postgres \
+    -e POSTGRES_PASSWORD=postgres \
+    --health-cmd="pg_isready" \
+    --health-interval=10s \
+    --health-timeout=5s \
+    --health-retries=5 \
+    -p 5432:5432 \
+    postgres
+echo "Wait for 5 seconds please..."
+sleep 5
+sudo docker exec -i postgres bash << EOF
+    sed -i -e 's/max_connections = 100/max_connections = 1000/' /var/lib/postgresql/data/postgresql.conf
+    sed -i -e 's/shared_buffers = 128MB/shared_buffers = 2GB/' /var/lib/postgresql/data/postgresql.conf
+EOF
+sudo docker restart --time 0 postgres
+```
+
+### Build
+To build the project, run ```./mvnw install``` in Unix shell or PowerShell. This will generate API interfaces from the
+OpenAPI specification in ```design/API/NT-API.yml```, compile the project, and run tests.
+
+### Run
+After the previous step, you will find the jar file in the ```target``` directory. Run
+```java -jar ./target/cheese-0.0.1-SNAPSHOT.jar``` (replace the jar file name with the actual one) to run this project.
+
+### Format
+To format the code, run ```./mvnw spotless:apply``` in Unix shell or PowerShell.
+
+## Database Migration
+
+### Test
+You do not need to migrate the database manually during testing. In ```pom.xml```, we set ```spring.jpa.hibernate.ddl-auto```
+to ```update``` when Maven is running tests. This means that Hibernate will automatically create tables and columns in
+the database.
+
+### Production
+In production, you need to migrate the database manually. Our build system will generate ```design/DB/CREATE.sql``` each
+time you run ```./mvnw install```. This file is added to git, so you can see how the schema changes.

design/API/About.md

@@ -0,0 +1,21 @@
+# Integrated Swagger API Specification
+
+## Introduction
+We have used `swagger-codegen-maven-plugin` to generate api interfaces from the swagger specification file. This is an automated process, and the generated code is placed in `target/generated-sources/swagger` directory. You can directly use these interfaces in your code.
+
+## Swagger Version
+Swagger version of swagger specification file should be Swagger 3.0
+
+If you are using Swagger 2.0, you can convert it to Swagger 3.0 using the following command:
+
+```bash
+pnpm install -g api-spec-converter
+api-spec-converter          \
+    --from swagger_2        \
+    --to openapi_3          \
+    --syntax yaml           \
+    --order default         \
+    --check                 \
+    --dummy                 \
+    your-swagger-3.0.yaml
+```