Step 1: Install Docker

If you're on a desktop, Docker Desktop is the easiest way to install Docker. Otherwise, see the Docker documentation for how you should install.

If you're on linux, you may need to add your user to the docker group.

sudo usermod -aG docker $USER

Step 2: Setup Authentication Provider

While you can run the API without authentication by setting AUTH_PROVIDERS to an empty string, it is highly recommended to set up at least one method of authentication, especially if your API will be accessible from the internet.

Currently, we support Discord and generic OIDC as authentication providers.

Auth Provider Setup Guides

See Authentication for more info on setting up a specific auth provider.

Discord is the easiest and recommended.

Step 3: Generate Secret Key

Run the following command to generate a secret key:

docker run --rm ghcr.io/cclloyd/planeshift:latest gen_secret

Take note of the secret generated, and set SECRET_KEY to it in your docker-compose.yml

Step 4: Modify the default docker compose file

Fill in the required env vars above in the provided docker-compose.yml file.

For PlaneShift this includes

• Your secret key
• database credentials
• Auth provider credentials for at least one provider
• Foundry credentials

For mongo, just change the default password to something else.

Step 5: Create the database

If you need to create the database first ensure mongo is running

docker compose up -d mongo

Then enter a mongo shell

docker compose exec -it mongo mongosh -u planeshift
<enter your password>
use planeshift;
db.createUser({
  user: "planeshift",
  pwd: "planeshift",
  roles: [
    { role: "dbOwner", db: "planeshift" }
  ]
});

Step 6: Run the API

Once you have done all the above, you can start the API

docker compose up -d

Now you can access it at whatever url you set up, or localhost:3000 if you're just running it locally.

You can see the full schema available at /api/swagger.