|
1 | | -This page lists the steps required to start developing [Gramps Web API](https://github.com/gramps-project/gramps-web-api/). It will be assumed that you are using Ubuntu Linux. |
| 1 | +# Backend development setup |
2 | 2 |
|
3 | | -### Python version |
| 3 | +This page lists the steps required to start developing [Gramps Web API](https://github.com/gramps-project/gramps-web-api/), the backend (server component) of Gramps Web. |
4 | 4 |
|
5 | | -The Web API requires Python 3.7 or newer. |
6 | 5 |
|
7 | | -### Install Gramps |
| 6 | +## Prerequisites |
8 | 7 |
|
9 | | -The Web API requires the Gramps Python library to be importable. Starting from Gramps 5.2.0, it will be installable via `pip`. Right now, development is still based on Gramps 5.1.x, so the most convenient option is to install the Gramps `apt` package on Ubuntu |
| 8 | +The recommended development setup uses Visual Studio Code with devcontainers. This approach will create a preconfigured development environment with all the tools you need. To get started, you'll need the following ingredients: |
10 | 9 |
|
11 | | -``` |
12 | | -sudo apt install gramps |
13 | | -``` |
| 10 | +- [Docker](https://docs.docker.com/get-docker/) |
| 11 | +- [Visual Studio Code](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) installed |
| 12 | +- [Git](https://git-scm.com) |
14 | 13 |
|
15 | | -!!! info |
16 | | - Note that using the `gramps` Python package from Gramps installed with `apt` requires using the system Python interpreter, so you cannot work in a virtual environment. |
| 14 | +You can use Linux, macOS, or Windows as your operating system. |
17 | 15 |
|
18 | | -### Clone the Web API repository |
19 | 16 |
|
20 | | -Clone the Web API to your PC (assuming you have set up an SSH key with Github) using |
| 17 | +## Getting started |
21 | 18 |
|
22 | | -``` |
23 | | -git clone [email protected]:gramps-project/gramps-web-api.git |
24 | | -cd gramps-web-api |
25 | | -``` |
| 19 | +1. Open the [Gramps Web API repository](https://github.com/gramps-project/gramps-web-api) and click "fork" |
| 20 | +2. Clone your forked repository to your local machine using Git |
| 21 | +3. Open the cloned repository in Visual Studio Code. When prompted, select "Reopen in Container" or manually open the command palette (Ctrl+Shift+P or Cmd+Shift+P) and select "Dev Containers: Rebuild and Reopen in Container". |
| 22 | +4. Wait for the dev container to build and start. This may take a few minutes, especially the first time. |
26 | 23 |
|
27 | 24 |
|
28 | | -### Install prerequisites |
| 25 | +## Tasks |
29 | 26 |
|
30 | | -To start development, please install the dependencies by running |
31 | | -``` |
32 | | -pip3 install -r requirements-dev.txt |
33 | | -``` |
| 27 | +If you are only modifying the backend code, you do not necessarily need to spin up a web server - unit tests use a Flask test client that allow simulating requests to the API without needing a running server. |
34 | 28 |
|
35 | | -### Install the library in editable mode |
| 29 | +However, running a server is useful if you |
36 | 30 |
|
37 | | -Run |
38 | | -``` |
39 | | -pip3 install -e . --user |
40 | | -``` |
| 31 | +- want to try out your changes with real HTTP requests (see [manual queries](queries.md)), |
| 32 | +- want to preview the impact of changes on the full Gramps Web application, or |
| 33 | +- also want to make simultaneous changes to the frontend (see [frontend development setup](../frontend/setup.md)). |
41 | 34 |
|
42 | | -### Set up pre-commit hooks |
43 | | - |
44 | | -To set up the pre-commit hooks for the repository, run |
45 | | -``` |
46 | | -pre-commit install |
47 | | -``` |
48 | | -in the repository root. This will e.g. make sure that all source files are nicely formatted with `black`. |
49 | | - |
50 | | -### Run tests |
51 | | - |
52 | | -To run the unit tests, run |
53 | | -``` |
54 | | -pytest |
55 | | -``` |
56 | | -in the repository root. |
57 | | - |
58 | | -### Generate a configuration file |
59 | | - |
60 | | -Example content: |
61 | | - |
62 | | -```python |
63 | | -TREE="My Family Tree" |
64 | | -SECRET_KEY="not_secure_enough" |
65 | | -USER_DB_URI="sqlite:///users.sqlite" |
66 | | -``` |
67 | | - |
68 | | -!!! warning |
69 | | - Do not use this configuration in production. |
70 | | - |
71 | | -See [Configuration](../../install_setup/configuration.md) for a full list of config options. |
72 | | - |
73 | | -!!! warning |
74 | | - Do not use your production database for development, but use a copy of it or the Gramps example database. |
75 | | - |
76 | | - |
77 | | -### Add users |
78 | | - |
79 | | - |
80 | | -You can add a user with owner permissions by running |
81 | | -``` |
82 | | -python3 -m gramps_webapi --config path/to/config user add owner owner --role 4 |
83 | | -``` |
84 | | -This uses username and password `owner`. |
85 | | - |
86 | | - |
87 | | -### Run the app in development mode |
88 | | - |
89 | | - |
90 | | -Run |
91 | | -``` |
92 | | -python3 -m gramps_webapi --config path/to/config run |
93 | | -``` |
94 | | -The API will be accessible at `http://127.0.0.1:5000` by default, which displays an empty page. Access your Gramps data using the API described by [gramps-project.github.io/gramps-web-api](https://gramps-project.github.io/gramps-web-api/). For example, to show people go to `http://127.0.0.1:5000/api/people` |
95 | | - |
96 | | -#### Options |
97 | | - |
98 | | -To choose a different port, add the `--port PORT` option, where `PORT` is a number. The default port is `5000`. |
99 | | - |
100 | | -To send the log data to a file, use `--log-file FILENAME`. The default is not to log to a file. |
101 | | - |
102 | | -To set the log level (for console or file) use `--debug-level LEVEL` where LEVEL is `info`, `debug`, `warning`, or `critical`. The default is `info`. |
103 | | - |
104 | | -If running the gramps-web-api server locally, the following additional flags may be useful: |
105 | | - |
106 | | -* `--use-wsgi` - adds a WSGI wrapper to the application. |
107 | | -* `--host IP` - the IP address to use for the WSGI listener. The default IP is `127.0.0.1`. |
108 | | -* `--max-workers NUMBER` - for the WSGI server. Default is set dynamically based on the number of CPUs. |
109 | | -* `--open-browser WHERE` - to open the browser on the default gramps-web-api page in a `tab` or a `window`. The default of `WHERE` is `no`, meaning to not open a browser tab or window. |
110 | | - |
111 | | -To find out more about the options, use `--help`. |
| 35 | +Running the server is simplified in the dev container by predefined tasks. You can run these tasks from the command palette (Ctrl+Shift+P or Cmd+Shift+P) by selecting "Tasks: Run Task" and then choosing one of the following: |
| 36 | +- "Serve Web API" - starts the Flask development server on port 5555 with debug logging enabled |
| 37 | +- "Start Celery worker" - starts a Celery worker to process background tasks. |
0 commit comments