Before you can start hacking away on waldo, you need to have the tools below to ensure everything works.
- Node.js - The current
- Rust - So our desktop app can build
- Yarn - Our package manager of choice
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
https://github.com/waldo-vision/waldo to your machine then navigate to it using the ‘cd’ console command.
You’ll need to install a few dependencies in order to run the dev server:
With those installed, you can download additional packages with yarn:
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
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
Update your .env file like so:
Be sure to also set the
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
/packages/web/.envto 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:
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.
The Project uses yarn workspaces, which are defined in
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
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
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
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.
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
- 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.
- You may not merge any pull requests unless a code review has been completed by the owners of this repository.
- Double check that IDE specific settings don’t make it into the Git repository.