Installation
A guide on how to install and run OrbitKit.
Introduction
OrbitKit is setup as a monorepo, which comes with three applications and many packages, here is the codebase structure:
We will go more in detail about every aspect of orbitkit later on, but this should give you a good idea of what to expect.
Prerequisites
Before you begin, ensure you have met the following requirements:
- You have
Bun
installed on your machine.
That is actually pretty much all you need!
Installation
With all that being said, we are ready to start using Orbitkit! We firstly need to clone it down to your machine and then we can install dependencies, configure environment variables and run it!
Configuring environment variables
You will need to set-up some environment variables in a .env.local
file in the apps/web
directory. We provide an example file in apps/web/.env.example
that you can copy over and input the values.
Here is how you can obtain each of the required values:
Database
The database that OrbitKit uses is Neon PostgreSQL. You should create a free account and input the database url given to you on the dashboard to be the value of the DATABASE_URL
environment variable.
Make sure that the DATABASE_URL
ends with ?sslmode=require
.
Uploadthing
Uploadthing is the service of choice in OrbitKit for file uploads, you should create an account and input the api keys into the .env.local
File.
Unkey (optional)
Unkey is the service of choice in OrbitKit for rate limiting, it is however optional as that if the UNKEY_ROOT_KEY
or UNKEY_NAMESPACE
variables are not supplied, no rate limiting is applied.
To obtain this key, head over to your unkey dashboard and create a new ratelimit namespace, then in your settings, create a new root key, that will be the value of your environment variable.
As for the namespace that you have created, you will need to put that as the value of the UNKEY_NAMESPACE
environment variable.
Posthog (optional)
Posthog is the service of choice in OrbitKit for analysis, it is however optional as that if the NEXT_PUBLIC_POSTHOG_HOST
or NEXT_PUBLIC_POSTHOG_KEY
variables are not supplied for the web app or PUBLIC_POSTHOG_KEY
and PUBLIC_POSTHOG_HOST
for the marketing app, no analysis is applied.
To obtain this key, head over to your posthog dashboard, then in your settings, find Project API Key
, that will be the value of the key environment variable.
As for the host use app.posthog.com
or eu.posthog.com
depending on your region.
OAuth
OrbitKit currently ships with two authentication providers, Google and Github. You will need to create an OAuth application on the respective platforms and input the values into the .env.local
file.
Based on the environment variables set, authentication will be provided. For
example, setting AUTH_GITHUB_ID
and AUTH_GITHUB_SECRET
will make it so
that Github OAuth is then activated on the web application. The same is true
for Google OAuth.
Reset changelog and versions
When you first clone the repository, you should reset the changelog and project metadata to start fresh. You can do so by running the following commands:
The update:workspace
command has the following options:
Note: If you want to pass special characters or spaces in the author flag, you should wrap the value in two sets of quotes
'""'
e.g.'"Ahmed Elsakaan - https://orbitkit.dev"'
.
Running the project
Now that you have set up the environment variables, you can run the project!
This command will apply the necessary database migrations and start the development tasks on all of the apps & packages.
You should be able to access the web app on http://localhost:3000
, the marketing website on http://localhost:4321
and the documentation website on http://localhost:3002
.
For more info about the commands available to you, you can check out the Commands page.