mirror of
https://github.com/Gozargah/Marzban.git
synced 2026-05-17 08:35:56 +03:00
b038f5eecf
Details: - Installing `typer-cli` note added. - CLI name set to empty string to match the current document.
69 lines
3.9 KiB
Markdown
69 lines
3.9 KiB
Markdown
# Contribute to Marzban
|
|
Thanks for considering contributing to Marzban!
|
|
|
|
## Questions
|
|
|
|
Please don't ask your questions in issues. Instead, use one of the following ways to ask:
|
|
- Ask on our telegram group: [@Gozargah_Marzban](https://t.me/gozargah_marzban)
|
|
- Ask on our [GitHub Discussions](https://github.com/gozargah/marzban/discussions) for long term discussion or larger questions.
|
|
|
|
|
|
## 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 Marzban, Xray and docker (if you use docker) you are using.
|
|
|
|
|
|
# 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.
|
|
|
|
## Branches
|
|
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.
|
|
|
|
## Project Structure
|
|
```
|
|
.
|
|
├── app # Backend code (FastAPI - Python)
|
|
│ └── dashboard # Frontend code (React - Typescript)
|
|
├── cli # CLI code (Typer - Python)
|
|
└── xray_api # Client of Xray's gRPC API
|
|
```
|
|
|
|
## Backend
|
|
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.
|
|
|
|
### Python Code Formatting
|
|
To maintain consistency in the codebase, we require all code to be formatted using
|
|
```bash
|
|
autopep8 <file> --max-line-length 120
|
|
```
|
|
|
|
## Frontend
|
|
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.
|
|
|
|
### Components Library
|
|
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.
|
|
|
|
## Marzban CLI
|
|
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 (`typer-cli` package needs to be installed first):
|
|
|
|
```bash
|
|
$ PYTHONPATH=$(pwd) typer marzban-cli.py utils docs --name "" --output ./cli/README.md
|
|
```
|
|
|
|
## Debug Mode
|
|
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.
|
|
|
|
Note that you must first install the necessary npm packages by running npm install inside the app/dashboard directory before running in debug mode.
|
|
```bash
|
|
cd app/dashboard
|
|
npm install
|
|
cd ../..
|
|
```
|
|
|
|
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."
|
|
|