Self‐hosting

This guide will take you through hosting your own instance of Crab Fit.

Please note that because Crab Fit is licensed under the GNU GPLv3. Ensure you consult the license file for all restrictions if you decide to use or modify the code.

Choose Your Infrastructure

Before you begin, you'll need to choose where you want to host the frontend, API and database. The choice is up to you, although see below for some suggestions.

Frontend

The Next.js docs have a great page about deploying. The easiest method will be using Vercel, however they have listed some alternatives.

You may also use a personal machine, raspberry pi, etc. as long as you have node and yarn installed. Note this may make setting up a domain and SSL certificates more difficult.

API

The API is written using rust, and so compiles down to an executable you can run from any operating system. I personally recommend using Fly.io, which works using Docker. A Dockerfile is provided in the repo which is designed to run the API on fly.io, but should work anywhere you can use Docker, such as an Amazon EC2 instance, DigitalOcean droplet, etc.

If you do use the provided Dockerfile, don't forget to change --features datastore-adaptor in the compilation step to match your chosen database below.

Database

The Crab Fit API requires a database to store events and availability, and is designed to work with multiple types of databases. You will need to choose one from this table.

Environment Variables

After you have chosen your infrastructure, you'll need to make sure the correct environment variables are set for the frontend and API.

Frontend

Variable	Example	About
NEXT_PUBLIC_API_URL	https://api.crab.fit	This needs to be set to where your API will be hosted, so the frontend can communicate with it.
NEXT_PUBLIC_GOOGLE_CLIENT_ID	123-abc.apps.googleusercontent.com	If you want the Google Calendar sync button to be enabled, you'll need to set up a Google oauth screen and API key. You can follow the steps in this Google guide until you reach "Set up the sample" to get started.
NEXT_PUBLIC_GOOGLE_API_KEY	AIzaabcdefghijklmnopqrstuvwxyz	See above

API

Variable	Example	About
FRONTEND_URL	https://crab.fit	This needs to be set to the address where your frontend will be hosted, to allow cross-origin requests. If this is set incorrectly you will see CORS errors in the browser console
CRON_KEY	abc123	This can be any string, and is not required. It can be used to protect the cleanup task endpoint of the API, see the API README for more details.

Each database adaptor may require some environment variables to be set in order to function. Visit the README for a specific adaptor to find out what you'll need to set, e.g. the SQL adaptor requires DATABASE_URL to be set.

Current Deployment

For an example, let's take a look at how the current production instance is running at https://crab.fit.

Frontend

The frontend is being hosted with Vercel, who have first-class support for Next.js apps.

Environment Variables

There are 3 environment variables set up currently through the Vercel project settings:

NEXT_PUBLIC_API_URL="https://api.crab.fit"
NEXT_PUBLIC_GOOGLE_CLIENT_ID="***"
NEXT_PUBLIC_GOOGLE_API_KEY="***"

Note that the Google client id and API key are set to allow Google Calendar syncing. This feature will be disabled if these variables are not present.

API

The API is being hosted with Fly.io, which is a service that can run Docker images and provides things like SSL certificates and an IP address.

Dockerfile

You can visit the dockerfile that's used to run the current API in the repo, note that the compilation step uses --features datastore-adaptor to tell the API to compile with the Google Datastore database adaptor. This also requires the GCP_CREDENTIALS env variable (see below).

Environment Variables

The API currently has 3 environment variable set using the fly secrets command.

FRONTEND_URL="https://crab.fit"
CRON_KEY="***"
GCP_CREDENTIALS="***"

It's important that the frontend url is set correctly so the API can restrict cross-origin requests.

Note as well that a cron key is set to protect the tasks endpoint, and GCP credentials are set so that the API can connect to the Google Datastore, the current database.