You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+44-21Lines changed: 44 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,46 +8,69 @@ PlanarAlly consists of a client and a server component. If you want to run a dev
8
8
9
9
This project uses the gitflow branching strategy. This means that the master branch is intended for releases only. All pull requests should be done on the development branch.
10
10
11
-
When making a pull request, make sure the code is formatted properly.
11
+
### Format & Lint
12
12
13
-
For the server you can run `black .` in the server folder,
14
-
for the client you can run `npm run lint` in the client folder.
13
+
All code is required to be formatted and linted before it can be merged. To format and lint the server you need to run
14
+
15
+
```bash
16
+
uv run ruff format src
17
+
uv run ruff check src
18
+
```
19
+
To format and lint the client code you need to run
20
+
21
+
```bash
22
+
npm run format
23
+
npm run lint
24
+
```
15
25
16
26
## Server
17
27
18
28
All code of the server is located in the `server` folder at the root level of the git repository.
19
29
The server infrastructure runs on aiohttp, a python async webframework.
20
30
Install python >=3.6 (a virtual environment is recommended) and install all the dependencies.
21
31
22
-
### Example install
32
+
### Install & Setup
23
33
24
-
Lines 2 and 3 are optional. Replace `python` with `python3` if the default is not py3.
34
+
This project uses uv to manage its dependencies and run the server so to begin you will need to install UV from its official site. UV will automatically create the virtual environment so you only need to run the application to get going. Optionally you can run `uv sync` in the server directory to install the dependencies.
25
35
26
-
```
27
-
cd server
28
-
python -m venv env
29
-
source env/bin/activate
30
-
pip install -r requirements.txt
36
+
> This project uses Python 3 so ensure that python and UV are running with the correct version.
37
+
38
+
You can create a config.toml in the server/data directory to change settings. You can find the configuration values at the [PlanarAlly Site](https://www.planarally.io/server/management/configuration/)
39
+
40
+
You can change the host & port configuration in the config.toml to adjust for your application needs. For example
41
+
42
+
```toml
43
+
[webserver.connection]
44
+
type = "hostport"
45
+
host = "0.0.0.0"
46
+
port = 8000
31
47
```
32
48
33
-
Change the server.cfg file to what you wish to use and you can start the webserver with a simple
49
+
### Running the server
34
50
35
-
`python planarserver.py`
51
+
You can run the server in either development or production mode. In development mode, requests are redirected to the Vite server, enabling real-time updates while building the client application. In production mode, the server instead serves the static assets generated from the client build.
36
52
37
-
The above command will start the server in production mode. This expects build js artifacts to be created and available to the server. (These can be created by building a production version of the client).
38
-
To use the server together with a development version of the client instead use:
53
+
#### Production
39
54
40
-
`python planarserver.py dev`
55
+
The command will start the server in production mode. This expects build js artifacts to be created and available to the server. (These can be created by building a production version of the client).
56
+
57
+
```bash
58
+
uv run planarserver.py
59
+
```
60
+
61
+
#### Development
62
+
63
+
To use the server together with a development version of the client instead use:
41
64
42
-
If both server and client are running you can launch PA by visiting http://localhost:8000
65
+
`uv run planarserver.py dev`
43
66
44
-
It is strongly recommended to also install the devdependencies ('requirements-dev.txt) as this contains the formatter that is used for PA.
67
+
You will need to then start the client app. Then you will want to launch your browser at the host & port for the PA server (**not the client**). By default that will be: http://localhost:8000
45
68
46
69
## Client
47
70
48
-
The client is written in typescript, editing the javascript file directly is strongly discouraged and any pull request that only changes the js file will also be declined.
71
+
The client is written in typescript, editing the javascript file directly is strongly discouraged and any pull request that only changes the js file will also be declined.
49
72
50
-
To get the client side up and running you'll need to install the dependencies with
73
+
Ensure you have the correct version of NPM installed (typically latest LTS). You can verify that by checking in the github actions [pull_request.yaml](.github/workflows/pull_request.yaml#65)To get the client side up and running you'll need to install the dependencies with
51
74
52
75
`npm i`
53
76
@@ -57,15 +80,15 @@ To build a production version use:
57
80
58
81
To build a development version use:
59
82
60
-
`npm run serve`
83
+
`npm run dev`
61
84
62
85
### Target version
63
86
64
87
As mentioned in the client and server steps, there's a difference between the development version and the production version. Make sure that you use the same target for both environments when building.
65
88
66
89
### The result
67
90
68
-
To actually view and interact with the result whether you use the development or the production version you simply need to browse to your localhost at port 8000 (by default).
91
+
To actually view and interact with the client app regardless of if you use the development or the production version. You will need to browse to your localhost at port 8000 (by default).
0 commit comments