Do you want to perform some development?

If you want to try the application locally, make some changes, and see how it looks like, we recommend using Docker Compose, since it requires very little setup. If you need IDE integration or debugging, we recommend setting up a development environment.

Docker Compose

With Docker Compose, you can have a local server and client running in minutes. All you need to do is to install Docker Compose on your machine.

If you’re on Linux, install it with the Docker Engine. Otherwise, you can get it by installing Docker Desktop.

Once you have it, run the following in the repo root:

docker compose up --build

That’s it! You can access your local server at http://localhost:8080. You don’t need to install any toolchain or compiler.

If you want to modify your application, change the files you need and re-run the Composer command. Docker will rebuild the application for you before launching.

Although this technique works great for a quick test, rebuilds take longer than using regular local development, and debugging is more difficult. We recommend setting up the required tools locally if you’re going to go beyond a quick test.

Setting up local development

Since we’re building a C++ server and a React client, you’ll need a bunch of tools. We recommend using Linux (or WSL if you’re on Windows). We provide installation instructions for Ubuntu, but all tools can be installed on any other system.

Building the C++ server

The following tools are required:

  • A C++17 compliant compiler. We recommend using gcc 10 (o above), or clang 11 (or above).

  • CMake 3.16 or above.

  • The OpenSSL development files (C headers and CMake module).

  • ICU development files (C headers and CMake module).

If you’re on Ubuntu, you can install them using:

sudo apt install g++ cmake libssl-dev libicu-dev

You also need Boost. Since Boost.Redis hasn’t been fully integrated into Boost yet, you need to do it manually:

# Downloads sources to ~/boost-src, installs to /opt/boost
# Get the source code
mkdir ~/boost-src
cd ~/boost-src
wget -q https://archives.boost.io/beta/1.87.0.beta1/source/boost_1_87_0_b1_rc2.tar.gz
tar -xf boost_1_87_0_b1_rc2.tar.gz
cd boost_1_87_0

# Build and install. Make sure you've got write access to /opt/boost,
# otherwise change the --prefix argument
./bootstrap.sh
./b2 --with-json --with-context --with-regex --with-url --with-test --with-charconv -d0 --prefix=/opt/boost install
rm -rf ~/boost-src

You’ll also need a running Redis server. The easiest way to achieve this is with Docker:

docker run -d --name redis -p 6379:6379  redis:alpine

A MySQL server is also required. Again, we recommend using Docker:

docker run -d --name mysql -e MYSQL_ALLOW_EMPTY_PASSWORD=yes mysql:8

Now you can build your server using CMake (possibly from your IDE) by running this from the repository root:

mkdir build
cd build
cmake -DCMAKE_PREFIX_PATH=$HOME/boost ../server
cmake --build . -j 4

To run your webserver:

./main 0.0.0.0 8080 .

To run unit tests:

ctest --output-on-failure .

Running the client

You need Node 16.14 or later to run the client. You can download it or install it from a package manager. You will also need npm to install packages.

To verify that these tools are working, use:

node -v
npm -v

The next step is to install the Node packages required by the client:

cd client
npm install

Finally, you can run a development version of your client by running the following from client directory:

npm run dev

This will spawn a development server on http://localhost:3000/ with auto-refresh enabled (if you edit client files, your code will be hot-reloaded on file save).

The development server will route any incoming HTTP traffic on a URL matching http://localhost:3000/api/(.*) to the C++ server on http://localhost:8080/api/. If you’re C++ server is running on a different port, edit client/.env.development accordingly.

This routing ensures that both static files and the API are served from the same origin (which matches the production behavior), avoiding the problems associated with cross-origin requests.

To run the client unit tests, cd into client and run:

npm run test

Running the server integration tests

Integration tests are written in Python. They verify that the server works as expected by exercising the API directly. You need the C++ server running on port 8080 to execute them - the client is not required.

First, install Python 3 and pip:

sudo apt install python3 python3-pip

Then, install the required packages:

sudo pip install -r test/integration/requirements.txt

Finally, run the tests:

pytest