Getting Started


Before you can start hacking away on waldo, you need to have the tools below to ensure everything works.

  • Node.js - The current LTS version
  • Rust - So our desktop app can build
  • Yarn - Our package manager of choice

Deploying Services

Waldo Vision is dependent on a number of services, and depending on your needs, you can either self host, or use a cloud option for all of them. We recommend you self host for ease of development, but the cloud options do exist if you wish to use them.

Setting Up A Local Deployment

First, clone the git repo to your machine then navigate to it using the ‘cd’ console command.

Install Dependencies

You’ll need to install a few dependencies in order to run the dev server:

  • yarn - our JavaScript package manager.
  • docker - used for building and running containers.

With those installed, you can download additional packages with yarn:

yarn install


The app is configured via environment variables stored within a .env file in this directory.

Start by copying the example env file.

cp apps/web/.env.example apps/web/.env

# Open the file
vim apps/web/.env


If you plan on authenticating to Discord, make sure these credentials are set.


Follow this guide until you have added the Redirect URL. Be sure to set this to http://localhost:3000/api/auth/callback/discord.

Update your .env file like so:



If you plan on authenticating to GitHub, make sure these credentials are set.


Follow this guide. Be sure to set the Callback URL to http://localhost:3000/api/auth/callback/github.

Update your .env file like so:


Next Auth

Be sure to also set the NEXTAUTH_URL variable.

  • NEXTAUTH_URL=http://localhost:3000.

CloudFlare Turnstile

TODO: add CloudFlare configuration docs

You may also want to set the Cloudflare Turnstile keys so that submissions work.


TODO: add Youtube configuration docs

You may also want to set the Youtube API Key so that the review site works properly.

Note: YT API Key needs to be version 3 of the api.


The primary database used by the app is CockroachDB. You will need a working server to run this app locally.


You can easily spin up a new CockroachDB container with the docker compose file at the root of this repo.

# start the container
docker compose up -d

# Check that the container is running
docker ps

# If at any point you wish to shut down the container:
docker compose down

Alternatively, you can use CockroachDB’s free serverless tier if you don’t wish to self-host.

Option for Windows Users:

  • WARNING: Not recommended for development, use at your own risk, no support provided.
  • For Windows you can download the Beta Archive from Cockroachlabs and run the exe with ./cockroach.exe start-single-node --insecure
  • Then set the DATABASE_URL variable in /packages/database/.env and /packages/web/.env to the url displayed on start for postgresql
  • You even have a Web interface for management and debugging
  • WARNING BETA: (From their site: The CockroachDB executable for Windows is experimental and not suitable for production deployments. Windows 8 or higher is required.)


You will now need to set the DATABASE_URL variable in two configuration files:

  • apps/web/.env
  • packages/database/.env. If you haven’t already, create this file with cp packages/database/.env.example packages/database/.env.

If self-hosting using the docker compose method, then you can set your variable like so:



With your configuration set, you should be ready to run the migrations needed for our ORM to work.

yarn turbo db:generate
yarn turbo run db:push

Starting the server

With your environment configured, you should be ready to start the dev server.

yarn workspace web dev

Alternatively, you can build an optimized deployment of the app and deploy that instead.

# Build the app
yarn workspace web build

# Serve the app
yarn workspace web start

You should now be able to visit the website at http://localhost:3000.

Additional notes


The Project uses yarn workspaces, which are defined in /package.json.

Each submodule (database/webfrontend/webbackend/desktop app) defines its own package.json which is then used by yarn to run commands on it.

For example, running the webfrontend can be done with: yarn workspace web start.

Switching git branches

If you checkout git branches/commits you may encounter different versions of the database & packages. This may mean, that your build won’t compile, since the generated files are outdated. To fix it, run

yarn branch

which is just a fancy shortcut for (if you need to fix command failure):

yarn install #install dependencies
yarn turbo db:generate #generate new db model
yarn turbo run db:push #deploy the current db model to dev database

Picking work

Please follow the GitHub Projects, Milestones, and Issues:

  • Projects detail current side projects or larger systems.
  • Milestones detail current priority goals.
  • Issues detail individual features, bugs and tweaks to work on.

When picking work, please take note of an issue’s labels. For example, we ask that you consider issues marked as critical or bug to be of the highest priority. Issues marked as good first issue are a good place to start, and anything tagged with help wanted is something we are actively looking for help with. Once you have chosen an issue, please assign yourself to it, and/or leave a comment on the issue to let us know you are working on it.

Please keep in touch with our team via Discord, so we know who’s working on what.

Before you commit

When contributing to this repository, please first discuss the change you wish to make via issue, email, Discord, or any other method with the owners of this repository before making a change.

We also ask that you test all your changes, never commit a secret, and follow Conventional Commits for your commit messages.

Note we have a code of conduct, please follow it in all your interactions with the project.


We use Prettier to ensure consistent formatting across the codebase.

Ensure your changes have been properly formatted by running yarn run format.

Integration Tests

We utilize integration tests to verify that our APIs are working as intended and any changes made do not break existing endpoints.

Please ensure all tests are passed before opening a PR.

# Start the server in `dev` mode.
yarn workspace web dev

# OR build an optimized deployment
yarn workspace web build
node apps/web/.next/standalone/apps/web/server.js

# In a seperate tab
yarn turbo run tests:int

Pull Request Process

  1. Include your pull request with details of changes to the interface, this includes new environment variables, exposed ports, useful file locations and container parameters.
    • If you are adding a new feature, please include a screenshot of the feature in action.
    • Please also make sure you have updated the appropriate documentation to reflect any changes.
  2. You may not merge any pull requests unless a code review has been completed by the owners of this repository.
  3. Double check that IDE specific settings don’t make it into the Git repository.