Skip to main content

Development Environment Setup

Global System Installations​

info

For Windows users we recommend developing inside of WSL 2. A tutorial for setting it up can be found here. After the WSL has been installed, just install a Linux distribution you are comfortable with.

If you deliberately want a native Windows setup without WSL, see the Windows Setup (without WSL) page for the additional steps and known problems.

Before you can start developing with votura, you need to install the following:

  • git
  • node.js (we recommend using nvm)
  • docker (for Windows Users we recommend using Docker Desktop and configuring it to use the WSL 2 backend)

For the installation please refer to the official documentation of the tools.

You can run the following commands to check if you have installed the tools correctly:

git -v
node -v
npm -v
docker run hello-world

The docker command should output "Hello from Docker!".

Also make sure Git Large File Storage is installed. For that run

git lfs install

If git lfs is already installed this will not change anything.

Starting with the votura repository​

Now we can clone the votura repository to your preferred working directory:

git clone https://github.com/SE-UUlm/votura.git

After cloning the repository you should also set up signed commits, as they are required if you want to push to the remote repository. For this, please refer to this tutorial.

The next step is to run the following command in the root folder of your repository to install all dependencies of the project:

npm install

You should also add .env-files to the backend, frontend, db, e2e and hash directory. They should each contain the following variables. You may change their values but PEPPER and DATABASE_URL should be the same for all files.

Backend:

DATABASE_URL="postgresql://votura:votura@localhost:5432/votura?schema=public"
PEPPER="12345"
BITS_PRIME_P=20
KEY_GEN_TIMEOUT_MINUTES=15
SMTP_HOST="localhost"
SMTP_PORT="1025"
SMTP_SECURE="false"
MAIL_SENDER_NAME="Votura"
MAIL_SENDER_EMAIL="no-reply@votura.org"
FRONTEND_BASE_URL="http://localhost:5173"

The SMTP_* and MAIL_* variables configure outgoing email (e.g. password reset emails). For local development they point at the Mailpit service that is started together with the database via docker compose (see the db package). You can view all emails sent during development in the Mailpit web UI at http://localhost:8025. FRONTEND_BASE_URL is used to build links (such as the password reset link) that point back to the frontend.

Frontend:

BACKEND_BASE_URL="http://localhost:4000"

db:

DATABASE_URL="postgresql://votura:votura@localhost:5432/votura?schema=public"
PEPPER="12345"

e2e:

PEPPER="12345"

hash:

PEPPER="12345"

Build the internal packages​

Before you start an app for the first time, build the shared packages once. The apps import the compiled output (dist/) of the internal @repo/* packages, so they have to be built beforehand:

npx turbo build --filter=!@votura/docs

The --filter=!@votura/docs excludes the documentation build, which additionally requires a generated OpenAPI schema file that is not part of a fresh checkout (see the next step).

Generate the OpenAPI schema​

The documentation and the API pages are generated from packages/votura-validators/generated/voturaApiSchema.json, which is not committed to the repository. Generate it once (and again whenever the API definition changes):

npm run persist-schema -w @repo/votura-validators

For more details see the This Project Documentation page.

Set up the database​

Start the PostgreSQL database (this uses Docker):

npm run postgres-up -w @repo/db

Then create the necessary tables by running the migrations:

npm run migrate -w @repo/db
info

On native Windows (without WSL) the migration step can fail with ERR_UNSUPPORTED_ESM_URL_SCHEME or a pg_cron error. See the Windows Setup (without WSL) page for the explanation and the fix.

Start the development servers​

Now you are ready to start developing with votura. Start the backend (port 4000) and the frontend (port 5173) by running the following command in the apps/backend and apps/frontend directories respectively:

npm run start

For testing please see the documentation page for testing

Repository Structure​

We are using one monorepo (with the help of turborepo) for all parts of the votura project. Here is a nice introduction to monorepos.

The following image gives a brief overview of the structure of the repository:

folder structure of the repository

The votura repository is a npm project (sometimes also called as workspace). In the apps folder you can find all the applications of votura that can run independently, like the documentation, frontend or backend server. In the packages folder you can find all the shared packages that are used in the applications, such as the votura-crypto package or the typescript and eslint configuration.

Turborepo​

All these sub-projects are independent npm projects, but they have some dependencies and configuration to each other. You can navigate to the sub-projects and test, build or run them on their own. But the main advantage of turborepo is that you can run all the commands in the root folder, and you can run, test or build all the sub-projects at once.

Installing Workspace-Scoped Dependencies in a Turborepo Monorepo​

In a monorepo using Turborepo, dependencies can be shared across packages using workspace protocols defined in package.json. This also allows you to install internal packages as dependencies using workspace scoping.

To add a workspace-scoped dependency to an app, run:

npm install <package-name> -w <workspace-name>

Building the project​

Once the OpenAPI schema exists (see Generate the OpenAPI schema), you can build everything including the documentation. Try this in the root folder:

turbo build

As you can see this can take a while, because it builds all the sub-projects. But now you can try this a second time:

turbo build

As you see, the second time it is much faster. This is because turborepo caches the build results and only builds the sub-projects that have changed.

If you only want to build a specific sub-project from the root folder, you can do this with the following command:

turbo docs#build

The same applies to all other following commands (e.g. typecheck). For a list of all commands look for the turbo.json file in the projects root directory.

Instead of using the turbo command, you can also use npm run from the directory you want it to be used in. If you are in the docs-directory, running the following command will only build the docs.

npm run build

Turborepo automatically detects the dependencies between the sub-projects and builds them in the correct order. You can check the order for a specific task in the generated SVG by typing:

npx turbo run build --graph=graph.svg

Typecheck votura​

turbo typecheck

This command makes sure that the typing of variables etc. is consistent.

Linting votura​

Teamscale​

We are using a Teamscale server to run linting and static analysis on the votura codebase. You can connect your IDE (e.g. with the VSC Extension) to the Teamscale server to get real-time feedback on your code.

For VSC you must generate an Access Key in the Web view of Teamscale and add it to the configuration of the VSC Extension. Your settings.json-file should include something like this:

"teamscale.teamscaleServers": [
    {
        "serverUrl": "https://exia.informatik.uni-ulm.de/teamscale",
        "username": "yourUserName",
        "accessKey": "yourAccessKey",
        "trustAllCertificates": false
    }
],
  1. Please check all findings that Teamscale reports in your PR in GitHub and fix them.
  2. If you think there is a rule activated that is not useful for the votura project, please bring this up in the next meeting, so that it can be discussed with the whole team. If the team concludes the rule isn't useful, it can be reconfigured in the Teamscale webview.
  3. If you think the complaining rule is useful in general, but not for your specific case, you can add tolerate this finding with a comment in the Teamscale UI.
ESLint​
turbo lint

This command checks the code against the default rules applied by ESLint. You can also use ESLint directly in VSCode by installing the extension.

Format votura​

turbo format

This command formats the code using Prettier. Without proper formatting your PR will fail the pipeline.

Start all development servers​

turbo start

This command starts all apps at once. To start only the backend and the frontend, see Start the development servers above.