| 1 |
a47eb4c |
Dawsh |
2y ago |
## Questions |
| 2 |
a47eb4c |
Dawsh |
2y ago |
|
| 3 |
a47eb4c |
Dawsh |
2y ago |
Please don't ask your questions in issues. Instead, use one of the following ways to ask: |
| 4 |
a47eb4c |
Dawsh |
2y ago |
|
| 5 |
6c71685 |
Dawsh |
2y ago |
- Ask on our telegram group: [@marzneshins](https://t.me/marzneshins) |
| 6 |
6c71685 |
Dawsh |
2y ago |
- Ask on our [GitHub Discussions](https://github.com/khodedawsh/marzneshin/discussions) for long term discussion or |
| 7 |
6c71685 |
Dawsh |
2y ago |
larger questions. |
| 8 |
a47eb4c |
Dawsh |
2y ago |
|
| 9 |
a47eb4c |
Dawsh |
2y ago |
## Reporting issues |
| 10 |
a47eb4c |
Dawsh |
2y ago |
|
| 11 |
a47eb4c |
Dawsh |
2y ago |
Include the following information in your post: |
| 12 |
6c71685 |
Dawsh |
2y ago |
|
| 13 |
a47eb4c |
Dawsh |
2y ago |
- Describe what you expected to happen. |
| 14 |
a47eb4c |
Dawsh |
2y ago |
- Describe what actually happened. Include server logs or any error that browser shows. |
| 15 |
a47eb4c |
Dawsh |
2y ago |
- If possible, post your xray json config file and what you have set in env (by censoring critical information). |
| 16 |
6c71685 |
Dawsh |
2y ago |
- Also tell the version of Marzneshin, Xray and docker (if you use docker) you are using. |
| 17 |
a47eb4c |
Dawsh |
2y ago |
|
| 18 |
a47eb4c |
Dawsh |
2y ago |
# Submitting a Pull Request |
| 19 |
6c71685 |
Dawsh |
2y ago |
|
| 20 |
6c71685 |
Dawsh |
2y ago |
If there is not an open issue for what you want to submit, prefer opening one for discussion before working on a PR. You |
| 21 |
6c71685 |
Dawsh |
2y ago |
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 |
| 22 |
6c71685 |
Dawsh |
2y ago |
sidebar. No need to ask if you can work on an issue that interests you. |
| 23 |
a47eb4c |
Dawsh |
2y ago |
|
| 24 |
a47eb4c |
Dawsh |
2y ago |
## Branches |
| 25 |
6c71685 |
Dawsh |
2y ago |
|
| 26 |
6c71685 |
Dawsh |
2y ago |
Make sure to create a branch off your master branch, and then submit a PR to our master branch. |
| 27 |
a47eb4c |
Dawsh |
2y ago |
|
| 28 |
a47eb4c |
Dawsh |
2y ago |
## Project Structure |
| 29 |
6c71685 |
Dawsh |
2y ago |
|
| 30 |
a47eb4c |
Dawsh |
2y ago |
``` |
| 31 |
a47eb4c |
Dawsh |
2y ago |
. |
| 32 |
a47eb4c |
Dawsh |
2y ago |
├── app # Backend code (FastAPI - Python) |
| 33 |
6c71685 |
Dawsh |
2y ago |
├── dashboard # Frontend code (React - Typescript) |
| 34 |
6c71685 |
Dawsh |
2y ago |
└── cli # CLI code (Typer - Python) |
| 35 |
a47eb4c |
Dawsh |
2y ago |
``` |
| 36 |
a47eb4c |
Dawsh |
2y ago |
|
| 37 |
a47eb4c |
Dawsh |
2y ago |
## Backend |
| 38 |
6c71685 |
Dawsh |
2y ago |
|
| 39 |
6c71685 |
Dawsh |
2y ago |
Backend is built using FastAPI and uses SQLAlchemy as the ORM for database operations. Pydantic models can be found |
| 40 |
6c71685 |
Dawsh |
2y ago |
in the `app/models` directory, while all database-related operations and models are in the `app/db` directory. The |
| 41 |
6c71685 |
Dawsh |
2y ago |
migration scripts for the database (Alembic) can be found in the `app/db/migrations` directory. |
| 42 |
a47eb4c |
Dawsh |
2y ago |
|
| 43 |
a47eb4c |
Dawsh |
2y ago |
### Python Code Formatting |
| 44 |
6c71685 |
Dawsh |
2y ago |
|
| 45 |
6c71685 |
Dawsh |
2y ago |
To maintain consistency in the codebase, we require all code to be formatted using |
| 46 |
6c71685 |
Dawsh |
2y ago |
|
| 47 |
a47eb4c |
Dawsh |
2y ago |
```bash |
| 48 |
6c71685 |
Dawsh |
2y ago |
black . |
| 49 |
a47eb4c |
Dawsh |
2y ago |
``` |
| 50 |
a47eb4c |
Dawsh |
2y ago |
|
| 51 |
a47eb4c |
Dawsh |
2y ago |
## Frontend |
| 52 |
a47eb4c |
Dawsh |
2y ago |
|
| 53 |
6c71685 |
Dawsh |
2y ago |
The frontend follows a feature-oriented development structure. Features are essentially |
| 54 |
6c71685 |
Dawsh |
2y ago |
components, hooks, logics, services which provide user-experience that it coupled with domain |
| 55 |
6c71685 |
Dawsh |
2y ago |
and UI functionality. |
| 56 |
6c71685 |
Dawsh |
2y ago |
|
| 57 |
6c71685 |
Dawsh |
2y ago |
### Features |
| 58 |
6c71685 |
Dawsh |
2y ago |
`features` folder encapsulate all features. Features can be categorized in few groups, **Core domain**, **Support**. |
| 59 |
6c71685 |
Dawsh |
2y ago |
Core domain features deliver a set of solutions to the problem the application intened to resolve. Meanwhile |
| 60 |
6c71685 |
Dawsh |
2y ago |
Support features provide a set of solutions that are independent from domain model, however, they are necessary |
| 61 |
6c71685 |
Dawsh |
2y ago |
for the application to fully deliver the experience the user expect. |
| 62 |
6c71685 |
Dawsh |
2y ago |
|
| 63 |
6c71685 |
Dawsh |
2y ago |
### Generic Components |
| 64 |
6c71685 |
Dawsh |
2y ago |
|
| 65 |
6c71685 |
Dawsh |
2y ago |
`components` folder is a place for react generic components that will be reused by features. |
| 66 |
6c71685 |
Dawsh |
2y ago |
The same logic goes for `hooks`, `types`, folder. |
| 67 |
6c71685 |
Dawsh |
2y ago |
|
| 68 |
6c71685 |
Dawsh |
2y ago |
### Atomic components |
| 69 |
a47eb4c |
Dawsh |
2y ago |
|
| 70 |
6c71685 |
Dawsh |
2y ago |
`components/ui` folder is a place for atomic components that are the backbone of the application. |
| 71 |
6c71685 |
Dawsh |
2y ago |
These components are based on shadcn component template, however, depending when you are reading this, |
| 72 |
6c71685 |
Dawsh |
2y ago |
we probably have diverged a lot. |
| 73 |
6c71685 |
Dawsh |
2y ago |
|
| 74 |
6c71685 |
Dawsh |
2y ago |
### Utils |
| 75 |
6c71685 |
Dawsh |
2y ago |
|
| 76 |
6c71685 |
Dawsh |
2y ago |
These functions are generic and reused across codebase, although, they will be transfered to their |
| 77 |
6c71685 |
Dawsh |
2y ago |
own generic folder or feature folder as they grow in complexity and code usage. |
| 78 |
6c71685 |
Dawsh |
2y ago |
|
| 79 |
6c71685 |
Dawsh |
2y ago |
### Routes and pages |
| 80 |
6c71685 |
Dawsh |
2y ago |
|
| 81 |
6c71685 |
Dawsh |
2y ago |
`routes` folder is tanstack routing folder, containg pages and routing logic. |
| 82 |
6c71685 |
Dawsh |
2y ago |
|
| 83 |
6c71685 |
Dawsh |
2y ago |
├── routes # @tanstack/react-router routing |
| 84 |
6c71685 |
Dawsh |
2y ago |
├── features |
| 85 |
6c71685 |
Dawsh |
2y ago |
│ └── users # core domain feature |
| 86 |
6c71685 |
Dawsh |
2y ago |
│ └── nodes # core domain feature |
| 87 |
6c71685 |
Dawsh |
2y ago |
│ └── hosts # core domain feature |
| 88 |
6c71685 |
Dawsh |
2y ago |
│ └── entity-table # support feature |
| 89 |
6c71685 |
Dawsh |
2y ago |
│ └── github-repo # support feature |
| 90 |
6c71685 |
Dawsh |
2y ago |
├── components |
| 91 |
6c71685 |
Dawsh |
2y ago |
│ └── ui # atomic components |
| 92 |
6c71685 |
Dawsh |
2y ago |
|
| 93 |
6c71685 |
Dawsh |
2y ago |
To build the frontend you'll need the following dependencies: |
| 94 |
6c71685 |
Dawsh |
2y ago |
|
| 95 |
6c71685 |
Dawsh |
2y ago |
- pnpm |
| 96 |
6c71685 |
Dawsh |
2y ago |
|
| 97 |
6c71685 |
Dawsh |
2y ago |
then run `make dashboard-deps && make dashboard build` for it to build; or `make dashboard-dev` for development |
| 98 |
6c71685 |
Dawsh |
2y ago |
purposes. |
| 99 |
6c71685 |
Dawsh |
2y ago |
|
| 100 |
6c71685 |
Dawsh |
2y ago |
## Marzneshin CLI |
| 101 |
6c71685 |
Dawsh |
2y ago |
|
| 102 |
6c71685 |
Dawsh |
2y ago |
Marzneshin CLI is built using [Typer](https://typer.tiangolo.com/), and its commands' code can be found in `cli` |
| 103 |
6c71685 |
Dawsh |
2y ago |
directory. Its documentation is generated using [Typer CLI](https://typer.tiangolo.com/typer-cli/) which can be |
| 104 |
6c71685 |
Dawsh |
2y ago |
re-generated by navigating to project's root directory and running the following command: |
| 105 |
a47eb4c |
Dawsh |
2y ago |
|
| 106 |
a47eb4c |
Dawsh |
2y ago |
```bash |
| 107 |
6c71685 |
Dawsh |
2y ago |
$ PYTHONPATH=$(pwd) typer marzneshin-cli.py utils docs --name "marzneshin-cli" --output ./cli/README.md |
| 108 |
a47eb4c |
Dawsh |
2y ago |
``` |
| 109 |
a47eb4c |
Dawsh |
2y ago |
|
| 110 |
6c71685 |
Dawsh |
2y ago |
## Dev Mode |
| 111 |
6c71685 |
Dawsh |
2y ago |
|
| 112 |
6c71685 |
Dawsh |
2y ago |
To run the frontend in development mode use the following commands to install the dependencies, and then run the |
| 113 |
6c71685 |
Dawsh |
2y ago |
backend: |
| 114 |
a47eb4c |
Dawsh |
2y ago |
|
| 115 |
a47eb4c |
Dawsh |
2y ago |
```bash |
| 116 |
6c71685 |
Dawsh |
2y ago |
make dashboard-deps && make dashboard-dev |
| 117 |
a47eb4c |
Dawsh |
2y ago |
``` |
| 118 |
a47eb4c |
Dawsh |
2y ago |
|
| 119 |
6c71685 |
Dawsh |
2y ago |
run `make start` in another console. |