Configuring the environment
Before you get started with the installation, you need to configure the environment variables. Copy the contents of the.env.example
file found in the root directory of the cloned repository to .env
and add your values for the environment variables.
- Ensure that the environment values are not enclosed within quotes.
DATABASE_URL
: This is where you add your Postgres database URL.TOKEN_SALT_COMPLEXITY
: Defines the complexity of the SALT that is used for hashing - a higher number implies a more complex salt.MAGIC_LINK_TOKEN_VALIDITY
:Duration of the validity of the magic link being sent to sign in to Hoppscotch (in days).REFRESH_TOKEN_VALIDITY
: Validity of the refresh token for auth (in ms).ACCESS_TOKEN_VALIDITY
: Validity of the access token for auth (in ms).JWT_SECRET
,SESSION_SECRET
: Secret Keys for security purposes.REDIRECT_URL
: This is a fallback URL to debug when the actual redirects fail.WHITELISTED_ORIGINS
: URLs of Hoppscotch backend, admin dashboard, and the frontend app.VITE_ALLOWED_AUTH_PROVIDERS
: Allows you to specify which auth providers you want to enable.MAILER_SMTP_URL
: The SMTP URL for email delivery.MAILER_ADDRESS_FROM
: The email address that you would be using.RATE_LIMIT_TTL
: The time it takes to refresh the maximum number of requests being received.RATE_LIMIT_MAX
: The maximum number of requests that Hoppscotch can handle underRATE_LIMIT_TTL
.VITE_BASE_URL
: This is the URL where your deployment will be accessible from.VITE_SHORTCODE_BASE_URL
: A URL to generate shortcodes for sharing, can be the same asVITE_BASE_URL
.VITE_BACKEND_GQL_URL
: The URL for GraphQL within the instance.VITE_BACKEND_WS_URL
: The URL for WebSockets within the instance.VITE_BACKEND_API_URL
: The URL for REST APIs within the instance.VITE_APP_TOS_LINK
andVITE_APP_PRIVACY_POLICY_LINK
are optional and are used to configure the links to the Terms & Conditions and Privacy Policy.
Docker
Once the environment variables are configured, you may proceed to the next step of setting up the Hoppscotch instance. Currently, there are two ways to set up Hoppscotch:- Using individual containers for the services.
- Using the AIO container.
- Before proceeding further, ensure that you have a running instance of Postgres.
Using individual containers for the services
To self-host Hoppscotch Community Edition, you will need the following services running via Docker:- Hoppscotch frontend
- Hoppscotch backend
- Hoppscotch admin dashboard
- Ensure that the environment variables are configured in the
.env
file and the restart policy is mentioned.
PORT 3100
in the browser to setup and access the Hoppscotch instance.
Using the AIO container
The All-In-One (AIO) container is a single container that provides all the services required to run Hoppscotch. Pull the container from DockerHub with the following command:- Ensure that the environment variables are configured in the
.env
file and the restart policy is mentioned.
PORT 3100
in the browser to setup and access the Hoppscotch instance.
Subpath Based Access
To enable subpath based access the following.env
variable must be set to true, it is set to false by default.
Using individual containers for the services
When using the individual containers it is up to the users to configure a reverse proxy to allow requests made to a specific route to be rerouted to the relevant containers.Using the AIO container
When using AIO, when subpath access is set to true the services can be accessed from the following routesService | Route |
---|---|
Hoppscotch App | / |
Hoppscotch Admin App | /admin |
Hoppscotch Backend | /backend |
Migrations
Once the instance of Hoppscotch is up, you need to run migrations on the database to ensure that it has the relevant tables. Depending on how Hoppscotch was set up, the method to run the migrations changes.Using individual containers for the services
Run the following command to copy the ID of the backend container:Using the AIO container
Run the following command to copy the ID of the AIO container:Running migrations
Once the respective container ID is copied, execute the following command to open an interactive shell within the container to execute the migration command:.env
file containing the right .env
variables for the instance. On executing the aforementioned command will result in a shell being opened inside a instance of the container following which user can execute a database migration normally with
docker compose
to run the services the following command can be used to open a shell inside the backend (or AIO) service.