gitscope
/
← marzneshin / CONTRIBUTING.md / blame
Files Commits 446 Branches 1 Tags 43 Markers 4 README License
https://dev.kronoz.win/r/marzneshin.git
CONTRIBUTING.md · v0.3.0-alpha10
Source
1 a47eb4c Dawsh 2y ago # Contribute to Marzban
2 a47eb4c Dawsh 2y ago Thanks for considering contributing to Marzban!
3 a47eb4c Dawsh 2y ago
4 a47eb4c Dawsh 2y ago ## Questions
5 a47eb4c Dawsh 2y ago
6 a47eb4c Dawsh 2y ago Please don't ask your questions in issues. Instead, use one of the following ways to ask:
7 a47eb4c Dawsh 2y ago - Ask on our telegram group: [@Gozargah_Marzban](https://t.me/gozargah_marzban)
8 a47eb4c Dawsh 2y ago - Ask on our [GitHub Discussions](https://github.com/gozargah/marzban/discussions) for long term discussion or larger questions.
9 a47eb4c Dawsh 2y ago
10 a47eb4c Dawsh 2y ago
11 a47eb4c Dawsh 2y ago ## Reporting issues
12 a47eb4c Dawsh 2y ago
13 a47eb4c Dawsh 2y ago Include the following information in your post:
14 a47eb4c Dawsh 2y ago - Describe what you expected to happen.
15 a47eb4c Dawsh 2y ago - Describe what actually happened. Include server logs or any error that browser shows.
16 a47eb4c Dawsh 2y ago - If possible, post your xray json config file and what you have set in env (by censoring critical information).
17 a47eb4c Dawsh 2y ago - Also tell the version of Marzban, Xray and docker (if you use docker) you are using.
18 a47eb4c Dawsh 2y ago
19 a47eb4c Dawsh 2y ago
20 a47eb4c Dawsh 2y ago # Submitting a Pull Request
21 a47eb4c 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 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.
22 a47eb4c Dawsh 2y ago
23 a47eb4c Dawsh 2y ago ## Branches
24 a47eb4c Dawsh 2y ago When starting development on this project, please make sure to create a new branch off the `dev` branch. This helps to keep the `master` branch stable and free of any development work that may not be complete or fully tested.
25 a47eb4c Dawsh 2y ago
26 a47eb4c Dawsh 2y ago ## Project Structure
27 a47eb4c Dawsh 2y ago ```
28 a47eb4c Dawsh 2y ago .
29 a47eb4c Dawsh 2y ago ├── app # Backend code (FastAPI - Python)
30 a47eb4c Dawsh 2y ago │ └── dashboard # Frontend code (React - Typescript)
31 a47eb4c Dawsh 2y ago ├── cli # CLI code (Typer - Python)
32 a47eb4c Dawsh 2y ago └── xray_api # Client of Xray's gRPC API
33 a47eb4c Dawsh 2y ago ```
34 a47eb4c Dawsh 2y ago
35 a47eb4c Dawsh 2y ago ## Backend
36 a47eb4c Dawsh 2y ago Backend is built using FastAPI and uses SQLAlchemy as the ORM for database operations. All 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.
37 a47eb4c Dawsh 2y ago
38 a47eb4c Dawsh 2y ago ### Python Code Formatting
39 a47eb4c Dawsh 2y ago To maintain consistency in the codebase, we require all code to be formatted using
40 a47eb4c Dawsh 2y ago ```bash
41 a47eb4c Dawsh 2y ago autopep8 <file> --max-line-length 120
42 a47eb4c Dawsh 2y ago ```
43 a47eb4c Dawsh 2y ago
44 a47eb4c Dawsh 2y ago ## Frontend
45 a47eb4c Dawsh 2y ago Frontend is pre-built and served by FastAPI from the `app/dashboard/build` directory. To rebuild the frontend, first make sure you have the necessary dependencies installed by running `npm install` in the `app/dashboard` directory. Then, simply remove the `app/dashboard/build` directory and run the Python code again, and it will rebuild the frontend automatically.
46 a47eb4c Dawsh 2y ago
47 a47eb4c Dawsh 2y ago ### Components Library
48 a47eb4c Dawsh 2y ago Frontend uses `Chakra-UI` as the component library, so please adhere to the Chakra-UI approach when contributing. Strive to create components that are cohesive and serve a single purpose. Keep in mind that readability and maintainability are more important than brevity, so prioritize those factors when writing your code.
49 a47eb4c Dawsh 2y ago
50 a47eb4c Dawsh 2y ago ## Marzban CLI
51 a47eb4c Dawsh 2y ago Marzban 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:
52 a47eb4c Dawsh 2y ago
53 a47eb4c Dawsh 2y ago ```bash
54 a47eb4c Dawsh 2y ago $ PYTHONPATH=$(pwd) typer marzban-cli.py utils docs --name "marzban-cli" --output ./cli/README.md
55 a47eb4c Dawsh 2y ago ```
56 a47eb4c Dawsh 2y ago
57 a47eb4c Dawsh 2y ago ## Debug Mode
58 a47eb4c Dawsh 2y ago To run the project in debug mode with auto-reload, you can set the environment variable `DEBUG` to `true`. then by running the `main.py`, the backend and frontend will run separately on different ports.
59 a47eb4c Dawsh 2y ago
60 a47eb4c Dawsh 2y ago Note that you must first install the necessary npm packages by running npm install inside the app/dashboard directory before running in debug mode.
61 a47eb4c Dawsh 2y ago ```bash
62 a47eb4c Dawsh 2y ago cd app/dashboard
63 a47eb4c Dawsh 2y ago npm install
64 a47eb4c Dawsh 2y ago cd ../..
65 a47eb4c Dawsh 2y ago ```
66 a47eb4c Dawsh 2y ago
67 a47eb4c Dawsh 2y ago If you run the project with debug mode off and delete the `app/dashboard/build` directory, the frontend will be rebuilt automatically on the next run. However, no rebuild will occur while inside debug mode."
68 a47eb4c Dawsh 2y ago