diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 79150ff..4a172d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,68 +1,119 @@ -# 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. +- 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. ## 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. - +- Also tell the version of Marzneshin, 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. + +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. + +Make sure to create a branch off your master branch, and then submit a PR to our master branch. ## 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 +├── 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. 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. + +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 + +To maintain consistency in the codebase, we require all code to be formatted using + ```bash -autopep8 --max-line-length 120 +black . ``` ## 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. +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. + +### 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 -## 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: +`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. + +├── routes # @tanstack/react-router routing +├── features +│ └── users # core domain feature +│ └── nodes # core domain feature +│ └── hosts # core domain feature +│ └── entity-table # support feature +│ └── github-repo # support feature +├── components +│ └── ui # atomic components + +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 marzban-cli.py utils docs --name "marzban-cli" --output ./cli/README.md +$ PYTHONPATH=$(pwd) typer marzneshin-cli.py utils docs --name "marzneshin-cli" --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. +## Dev Mode + +To run the frontend in development mode use the following commands to install the dependencies, and then run the +backend: -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 ../.. +make dashboard-deps && make dashboard-dev ``` -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." - +run `make start` in another console. diff --git a/README.md b/README.md index ec6c233..0581676 100755 --- a/README.md +++ b/README.md @@ -141,13 +141,6 @@ If you are eager to run the project using the source code, check the section bel

Manual install (advanced)

 -Install xray on your machine - -You can install it using [Xray-install](https://github.com/XTLS/Xray-install) - -```bash -bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install -``` Clone this project and install the dependencies (you'd need Python >= 3.10) @@ -160,12 +153,15 @@ python3 -m pip install -r requirements.txt Alternatively, to have an isolated environment you can use [Python Virtualenv](https://pypi.org/project/virtualenv/) -Then run the following command to run the database migration scripts +To install dashboard dependencies and build the dashboard: ```bash -alembic upgrade head +make dashboard-deps +make dashboard-build ``` +note that you'll need pnpm and npm installed. + If you want to use `marzneshin-cli`, you should link it to a file in your `$PATH`, make it executable, and install the auto-completion: @@ -191,7 +187,7 @@ nano .env Eventually, launch the application using command below ```bash -python3 main.py +make start ``` To launch with linux systemctl (copy marzneshin.service file to `/var/lib/marzneshin/marzneshin.service`) @@ -291,7 +287,7 @@ the `UVICORN_HOST` and `UVICORN_PORT` environment variables. | NUMBER_OF_RECURRENT_NOTIFICATIONS | How many times to retry if an error detected in sending a notification (default: `3`) | | RECURRENT_NOTIFICATIONS_TIMEOUT | Timeout between each retry if an error detected in sending a notification in seconds (default: `180`) | | NOTIFY_REACHED_USAGE_PERCENT | At which percentage of usage to send the warning notification (default: `80`) | -| NOTIFY_DAYS_LEFT | When to send warning notification about expiration (default: `3`) | +| NOTIFY_DAYS_LEFT | When to send warning notification about expiration (default: `3`) | # API