|
| 1 | +# How to run a Prose Pod API locally? |
| 2 | + |
| 3 | +When developing the [Prose Pod Dashboard], one needs to easily start a Prose Pod API locally. |
| 4 | +This document explains how to do just this. |
| 5 | + |
| 6 | +## First time setup |
| 7 | + |
| 8 | +### Intall the tools you will need |
| 9 | + |
| 10 | +#### `git` |
| 11 | + |
| 12 | +We use Git as version control system so you will need to install it. |
| 13 | +You probably have it installed already, but if you don't, have a look at |
| 14 | +[Git - Installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). |
| 15 | + |
| 16 | +#### `task` |
| 17 | + |
| 18 | +Instead of using [GNU Make], we are using [Task] for its simplicity and flexibility. |
| 19 | +You can find installation instructions on [taskfile.dev/installation], |
| 20 | +or just run the folowing on macOS: |
| 21 | + |
| 22 | +```bash |
| 23 | +brew install go-task |
| 24 | +``` |
| 25 | + |
| 26 | +To list all available commands, use: |
| 27 | + |
| 28 | +```bash |
| 29 | +task -a |
| 30 | +``` |
| 31 | + |
| 32 | +#### Docker |
| 33 | + |
| 34 | +We need to build and run Docker container so you must have Docker installed. |
| 35 | +See [Install | Docker Docs](https://docs.docker.com/engine/install/). |
| 36 | + |
| 37 | +#### `cross` |
| 38 | + |
| 39 | +To build the Docker image locally, we need to cross-compile Rust code for a different architecture. |
| 40 | +To avoid cluttering your local environment, we use [`cross`] which handles everything transparently. |
| 41 | +You can find installation instructions on [github.com/cross-rs/cross#installation], or just run the following: |
| 42 | + |
| 43 | +```bash |
| 44 | +cargo install cross --git https://github.com/cross-rs/cross |
| 45 | +``` |
| 46 | + |
| 47 | +### Initialize your environment |
| 48 | + |
| 49 | +To avoid you having to copy-paste tons of commands, we hid all of the logic behind helper scripts |
| 50 | +which you can invoke using `task`. The first task to run is `local-init`. |
| 51 | + |
| 52 | +But before that, you must declare where you want the repositories to be |
| 53 | +(replace `???` by the desired location): |
| 54 | + |
| 55 | +```sh |
| 56 | +export PROSE_POD_SERVER_DIR=??? |
| 57 | +export PROSE_POD_API_DIR=??? |
| 58 | +export PROSE_POD_SYSTEM_DIR=??? |
| 59 | +``` |
| 60 | + |
| 61 | +Then, run: |
| 62 | + |
| 63 | +```sh |
| 64 | +git clone https://github.com/prose-im/prose-pod-api.git "${PROSE_POD_API_DIR:?}" |
| 65 | +git -C "${PROSE_POD_API_DIR:?}" submodule update --init |
| 66 | +task --taskfile "${PROSE_POD_API_DIR:?}"/Taskfile.yaml local-init |
| 67 | +``` |
| 68 | + |
| 69 | +> [!TIP] |
| 70 | +> To avoid having to export the environment variables every time, you can add them to a local `.env` file |
| 71 | +> which will be sourced automatically when you run the next commands: |
| 72 | +> |
| 73 | +> ```sh |
| 74 | +> echo "export PROSE_POD_SERVER_DIR='${PROSE_POD_SERVER_DIR:?}' |
| 75 | +> export PROSE_POD_API_DIR='${PROSE_POD_API_DIR:?}' |
| 76 | +> export PROSE_POD_SYSTEM_DIR='${PROSE_POD_SYSTEM_DIR:?}'" \ |
| 77 | +> >> "${PROSE_POD_API_DIR:?}"/paths.env |
| 78 | +> ``` |
| 79 | +
|
| 80 | +> [!TIP] |
| 81 | +> To run the `task` commands, you will have to `cd` into the Prose Pod API repository, |
| 82 | +> or invoke `task` telling it where to find the Taskfile. If you prefer the latter scenario, |
| 83 | +> you can export `PROSE_POD_API_DIR` in your `~/.zprofile` (or equivalent) and call |
| 84 | +> `task --taskfile "${PROSE_POD_API_DIR:?}"/Taskfile.yaml <task>` instead of `task <task>`. |
| 85 | +
|
| 86 | +## Run the API |
| 87 | +
|
| 88 | +At the root of the `prose-pod-api` repository, run: |
| 89 | +
|
| 90 | +```sh |
| 91 | +task local-update |
| 92 | +``` |
| 93 | +
|
| 94 | +## When you want to update one of the repositories |
| 95 | + |
| 96 | +At the root of the `prose-pod-api` repository, run: |
| 97 | + |
| 98 | +```sh |
| 99 | +task local-update |
| 100 | +``` |
| 101 | + |
| 102 | +## When you want to start fresh with a Prose Pod API that has no data |
| 103 | + |
| 104 | +At the root of the `prose-pod-api` repository, run: |
| 105 | + |
| 106 | +```sh |
| 107 | +task local-reset |
| 108 | +``` |
| 109 | + |
| 110 | +OR do the "Initialize your environment" phase again but with different directory paths. |
| 111 | +This way you can have multiple instances of the API with different states. |
| 112 | + |
| 113 | +[Prose Pod Dashboard]: https://github.com/prose-im/prose-pod-dashboard "prose-im/prose-pod-dashboard: Prose Pod dashboard. Static Web application used to interact with the Prose Pod API." |
| 114 | +[Task]: https://stepci.com/ "Task" |
| 115 | +[GNU Make]: https://www.gnu.org/software/make/ "Make - GNU Project - Free Software Foundation" |
| 116 | +[`cross`]: https://github.com/cross-rs/cross "cross-rs/cross: “Zero setup” cross compilation and “cross testing” of Rust crates" |
| 117 | +[github.com/cross-rs/cross#installation]: https://github.com/cross-rs/cross?tab=readme-ov-file#installation "cross-rs/cross: “Zero setup” cross compilation and “cross testing” of Rust crates" |
| 118 | +[taskfile.dev/installation]: https://taskfile.dev/installation/ "Installation | Task" |
0 commit comments