diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml new file mode 100644 index 0000000..fd6617b --- /dev/null +++ b/.github/workflows/ci.yaml @@ -0,0 +1,50 @@ +name: Docs CI + +on: + push: + branches: ["main"] + pull_request: + +concurrency: + group: "pages" + cancel-in-progress: false + +defaults: + run: + shell: bash + +jobs: + build: + runs-on: ubuntu-latest + env: + HUGO_VERSION: 0.126.3 + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 # fetch all history for .GitInfo and .Lastmod + submodules: recursive + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: "1.22" + - name: Setup Pages + id: pages + uses: actions/configure-pages@v4 + - name: Setup Hugo + run: | + wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \ + && sudo dpkg -i ${{ runner.temp }}/hugo.deb + - name: Build with Hugo + env: + # For maximum backward compatibility with Hugo modules + HUGO_ENVIRONMENT: production + HUGO_ENV: production + run: | + hugo \ + --gc --minify \ + --baseURL "${{ steps.pages.outputs.base_url }}/" + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ./public diff --git a/.github/workflows/pages.yaml b/.github/workflows/deploy.yaml similarity index 98% rename from .github/workflows/pages.yaml rename to .github/workflows/deploy.yaml index 984ce1f..2424462 100644 --- a/.github/workflows/pages.yaml +++ b/.github/workflows/deploy.yaml @@ -1,5 +1,5 @@ # Sample workflow for building and deploying a Hugo site to GitHub Pages -name: Deploy Hugo site to Pages +name: Deploy on: # Runs on pushes targeting the default branch diff --git a/content/docs/contribution-guide/_index.md b/content/docs/contribution-guide/_index.md deleted file mode 100644 index 6f5f97a..0000000 --- a/content/docs/contribution-guide/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Developer Guide -weight: 4 ---- diff --git a/content/docs/contribution-guide/codebase.md b/content/docs/contribution-guide/codebase.md deleted file mode 100644 index e69de29..0000000 diff --git a/content/docs/developer-guide/_index.md b/content/docs/developer-guide/_index.md new file mode 100644 index 0000000..54a6c3b --- /dev/null +++ b/content/docs/developer-guide/_index.md @@ -0,0 +1,52 @@ +--- +title: Developer Guide +weight: 4 +--- + +# Contribution Guideline + +This series of documents is dedicated to people whom want to understand +the codebase, architecture, and the contribution guideline. + +### Reporting issues + +Include the following information in your post: + +- Describe what you expected to happen. +- Describe what actually happened. Include server logs or any error that browser shows. +- If possible, post your xray json config file and what you have set in env (by censoring critical information). +- Also tell the version of Marzneshin, Xray and docker (if you use docker) you are using. + +{{< callout type="warning" >}} + +Please don't open issues solely intended to **questions**. Instead, use one of the following ways to ask: + +- Ask on our telegram group: [@marzneshins](https://t.me/marzneshins) +- Ask on our [GitHub Discussions](https://github.com/khodedawsh/marzneshin/discussions) for long term discussion or + larger questions. + +{{< /callout >}} + +### Submitting a Pull Request + +If there is not an open issue for what you want to submit, prefer opening one for discussion before working on a PR. You +can work on any issue that doesn't have an open PR linked to it or a maintainer assigned to it. These show up in the +sidebar. No need to ask if you can work on an issue that interests you. + +{{< callout type="warning" >}} + +Your PR name must follow the angular [commit conventions](https://www.conventionalcommits.org) `action(scope): desc`. +Otherwise your PR will be marked as broken and does not pass CI pipeline. + +{{< /callout >}} + +#### CI + +There are several actions quality checking your code. Make sure you pass all criteria's, especially **Sonar**. + +#### Branches + +Make sure to create a branch off your master branch, and then submit a PR to our master branch. + +The naming convetion for branches is `action/scope` plus the the number of issue if +there is one related. E.g. `feat/users-filter-admin`, `fix/nodes-settings-tab-123`. diff --git a/content/docs/contribution-guide/architecture.md b/content/docs/developer-guide/architecture.md similarity index 100% rename from content/docs/contribution-guide/architecture.md rename to content/docs/developer-guide/architecture.md diff --git a/content/docs/developer-guide/codebase.md b/content/docs/developer-guide/codebase.md new file mode 100644 index 0000000..d040003 --- /dev/null +++ b/content/docs/developer-guide/codebase.md @@ -0,0 +1,139 @@ +--- +title: Codebase +next: support +prev: docs/developer-guide +toc: true +weight: 1 +--- + +## Project Structure + +To rewrite the provided folder structure using the `filetree` notation based on the documentation in the image, the code will look like this: + +{{< filetree/container >}} +{{< filetree/folder name="marzneshin" state="open">}} +{{< filetree/folder name="app" >}} +Backend code +{{< /filetree/folder >}} +{{< filetree/folder name="dashboard" >}} +Frontend Code +{{< /filetree/folder >}} +{{< filetree/folder name="cli" >}} +CLI Code +{{< /filetree/folder >}} +{{< /filetree/folder >}} +{{< /filetree/container >}} + +| Folder name | Description | +| ----------- | ---------------------------------- | +| `app` | Backend code (FastAPI - Python) | +| `dashboard` | Frontend code (React - Typescript) | +| `cli` | CLI code (Typer - Python) | + +## Backend + +Backend is built using FastAPI and uses SQLAlchemy as the ORM for database operations. Pydantic models can be found +in the `app/models` directory, while all database-related operations and models are in the `app/db` directory. The +migration scripts for the database (Alembic) can be found in the `app/db/migrations` directory. + +### Python Code Formatting + +To maintain consistency in the codebase, we require all code to be formatted using + +```bash +black . +``` + +## Frontend + +The frontend follows a feature-oriented development structure. Features are essentially +components, hooks, logics, services which provide user-experience that it coupled with domain +and UI functionality. + +{{< filetree/container >}} +{{< filetree/folder name="routes" >}} +{{< /filetree/folder >}} +{{< filetree/folder name="features" >}} +{{< filetree/folder name="users" >}} +{{< /filetree/folder >}} +{{< filetree/folder name="nodes" >}} +{{< /filetree/folder >}} +{{< filetree/folder name="hosts" >}} +{{< /filetree/folder >}} +{{< filetree/folder name="entity-table" >}} +{{< /filetree/folder >}} +{{< filetree/folder name="github-repo" >}} +{{< /filetree/folder >}} +{{< /filetree/folder >}} +{{< filetree/folder name="components" >}} +{{< filetree/folder name="ui" >}} +{{< /filetree/folder >}} +{{< /filetree/folder >}} +{{< /filetree/container >}} + +| Folder name | Description | +| -------------- | ------------------------------ | +| `routes` | @tanstack/react-router routing | +| `features` | Feature folder | +| `users` | Core domain feature | +| `nodes` | Core domain feature | +| `hosts` | Core domain feature | +| `entity-table` | Support feature | +| `github-repo` | Support feature | +| `components` | Generic Components | +| `ui` | Atomic components | + +### Features + +`features` folder encapsulate all features. Features can be categorized in few groups, **Core domain**, **Support**. +Core domain features deliver a set of solutions to the problem the application intened to resolve. Meanwhile +Support features provide a set of solutions that are independent from domain model, however, they are necessary +for the application to fully deliver the experience the user expect. + +### Generic Components + +`components` folder is a place for react generic components that will be reused by features. +The same logic goes for `hooks`, `types`, folder. + +### Atomic components + +`components/ui` folder is a place for atomic components that are the backbone of the application. +These components are based on shadcn component template, however, depending when you are reading this, +we probably have diverged a lot. + +### Utils + +These functions are generic and reused across codebase, although, they will be transfered to their +own generic folder or feature folder as they grow in complexity and code usage. + +### Routes and pages + +`routes` folder is tanstack routing folder, containg pages and routing logic. + +To build the frontend you'll need the following dependencies: + +- pnpm + +then run `make dashboard-deps && make dashboard build` for it to build; or `make dashboard-dev` for development +purposes. + +## Marzneshin CLI + +Marzneshin CLI is built using [Typer](https://typer.tiangolo.com/), and its commands' code can be found in `cli` +directory. Its documentation is generated using [Typer CLI](https://typer.tiangolo.com/typer-cli/) which can be +re-generated by navigating to project's root directory and running the following command: + +```bash +$ PYTHONPATH=$(pwd) typer marzneshin-cli.py utils docs --name "marzneshin-cli" --output ./cli/README.md +``` + +## Dev Mode + +To run the frontend in development mode use the following commands to install the dependencies, and then run the +backend: + +```bash +make dashboard-deps && make dashboard-dev +``` + +run `make start` in another console. diff --git a/content/docs/contribution-guide/support.md b/content/docs/developer-guide/support.md similarity index 100% rename from content/docs/contribution-guide/support.md rename to content/docs/developer-guide/support.md