mirror/formbricks
1
0
Fork 0
mirror of https://github.com/formbricks/formbricks.git synced 2026-04-21 19:39:28 -05:00
Code Issues Packages Projects Releases 164 Wiki Activity

chore: restructure existing self hosting docs

Browse Source
This commit is contained in:
ShubhamPalriwala
2023-08-24 14:23:46 +05:30
parent ec7a1276fd
commit d20b713d18
5 changed files with 298 additions and 195 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/formbricks-com/app/docs/self-hosting/deployment/page.mdx
+6 -194
View File
@@ -6,204 +6,16 @@ export const meta = {
[Self-hosting]()
# Deploying Formbricks to production
# Self Hosting Formbricks
At Formbricks, we understand that different users have different needs, and we strive to cater to a wide variety of situations. This is why we provide three ways of running our application:
At Formbricks, we understand that different users have different needs, and we strive to cater to a wide variety of situations. This is why we currently provide three ways of running our application:
1. **Production Instance Setup with Shell Script on Ubuntu**: If you want to quickly set up a production instance of Formbricks on a server running Ubuntu, we've got you covered! This method utilizes a convenient shell script that takes care of everything, including Docker, Postgres DB, and SSL certificate configuration. The shell script will automatically install all the required dependencies and configure your server, making the process a breeze.
1. **Production Instance Setup with Shell Script on Ubuntu**: If you want to quickly set up a production instance of Formbricks on a server running Ubuntu, we've got you covered! This method utilizes a convenient shell script that takes care of everything, including Docker, Postgres DB, and SSL certificate configuration. The shell script will automatically install all the required dependencies and configure your server, making the process a breeze. Visit the [Production Instance Setup with a Bash Script Documentation](/docs/self-hosting/production).
2. **Fast Setup with a Pre-built Docker Image:** This method is designed for those who want to quickly set up and start using Formbricks without getting into the technicalities of Docker or the build process. When you choose this method, you're using an image that we've already built for you. The pre-built image is ready-to-run, and it only requires minimal configuration on your part. This approach is perfect for getting a functional instance of Formbricks up and running with minimal hassle. It's as easy as downloading the Docker image and firing up the container.
2. **Fast Setup with a Pre-built Docker Image:** This method is designed for those who want to quickly set up and start using Formbricks without getting into the technicalities of Docker or the build process. When you choose this method, you're using an image that we've already built for you. The pre-built image is ready-to-run, and it only requires minimal configuration on your part. This approach is perfect for getting a functional instance of Formbricks up and running with minimal hassle. It's as easy as downloading the Docker image and firing up the container. Visit the [Docker Setup Documentation](/docs/self-hosting/docker).
3. **Manual Setup by Building the Docker Image from Source:** This approach provides the flexibility to configure every aspect of your Formbricks instance, including environment variables that need to be set at build time. While we don't recommend changing the source code of Formbricks, this method allows you to set your own configuration that might be necessary for specific deployment needs. Keep in mind that this method requires a more in-depth understanding of Docker and the build process. However, the trade-off is the additional control and flexibility you gain, making it worth considering if you're a more advanced user or have very specific configuration needs.
3. **Manual Setup by Building the Docker Image from Source:** This approach provides the flexibility to configure every aspect of your Formbricks instance, including environment variables that need to be set at build time. While we don't recommend changing the source code of Formbricks, this method allows you to set your own configuration that might be necessary for specific deployment needs. Keep in mind that this method requires a more in-depth understanding of Docker and the build process. However, the trade-off is the additional control and flexibility you gain, making it worth considering if you're a more advanced user or have very specific configuration needs. Visit the [Advanced Setup from Source Documentation](/docs/self-hosting/from-source).
Please note that regardless of the method you choose, Formbricks is designed to be easy-to-use and flexible. So choose the method that best fits your comfort level and requirements, and start leveraging the power of Formbricks today!
Please note that regardless of the method you choose, Formbricks is designed to be easy-to-use and flexible. So choose the method that best fits your comfort level and requirements, and start leveraging the **power of Formbricks** today!
---
## (Most users: One-click Ubuntu setup) Running the Shell Script
This is the quickest way to get Formbricks up and running on an Ubuntu server. The shell script will automatically install all the required dependencies and configure your server, making the process a breeze.
### Requirements
Before you proceed, make sure you have the following:
- A Linux Ubuntu Virtual Machine deployed with SSH access.
- An A record set up to connect a custom domain to your instance. Formbricks will automatically create an SSL certificate for your domain using Let's Encrypt.
## Single Command Setup
Copy and paste the following command into your terminal:
```bash
/bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/formbricks/formbricks/main/docker/production.sh)"
```
The script will prompt you for the following information:
1. **Overwriting Docker GPG Keys**: If Docker GPG keys already exist, the script will ask if you want to overwrite them.
2. **Email Address**: Provide your email address for SSL certificate registration with Let's Encrypt.
3. **Domain Name**: Enter the domain name that Traefik will use to create the SSL certificate and forward requests to Formbricks.
That's it! After running the command and providing the required information, visit the domain name you entered, and you should see the Formbricks home wizard!
## (Manual Deployment) Running the pre-built Docker Image
### Requirements
Ensure `docker` & `docker compose` are installed on your server/system. Both are typically included with Docker utilities, like Docker Desktop and Rancher Desktop.
**Note**: `docker compose` without the hyphen is now the primary method of using docker-compose, according to the Docker documentation.
This is suitable for those who are testing Formbricks or running it with minimal to no modifications. For this we use the [public Docker image](https://hub.docker.com/r/formbricks/formbricks) and a simple docker-compose file.
1. **Create a New Directory for Formbricks**
Open a terminal and create a new directory for Formbricks, then navigate into this new directory:
```bash
mkdir formbricks-quickstart && cd formbricks-quickstart
```
2. **Download the Docker-Compose File**
Download the docker-compose file directly from the Formbricks repository:
```bash
curl -o docker-compose.yml https://raw.githubusercontent.com/formbricks/formbricks/main/docker/docker-compose.yml
```
3. **Generate NextAuth Secret**
Next, you need to generate a NextAuth secret. This will be used for session signing and encryption. The `sed` command below generates a random string using `openssl`, then replaces the `NEXTAUTH_SECRET:` placeholder in the `docker-compose.yml` file with this generated secret:
```bash
sed -i "/NEXTAUTH_SECRET:$/s/NEXTAUTH_SECRET:.\*/NEXTAUTH_SECRET: $(openssl rand -base64 32)/" docker-compose.yml
```
4. **Start the Docker Setup**
You're now ready to start the Formbricks Docker setup. The following command will start Formbricks together with a postgreSQL database using Docker Compose:
```bash
docker compose up -d
```
The `-d` flag will run the containers in detached mode, meaning they'll run in the background.
5. **Visit Formbricks in Your Browser**
After starting the Docker setup, visit http://localhost:3000 in your browser to interact with the Formbricks application. The first time you access this page, you'll be greeted by a setup wizard. Follow the prompts to define your first user and get started.
## Updating Formbricks
1. Stop the Formbricks stack
```bash
docker compose down
```
2. Pull the latest changes
```bash
docker compose pull
```
3. Update env vars as necessary.
4. Re-start the Formbricks stack
```bash
docker compose up -d
```
## (Advanced users) Build and Run Formbricks
### Requirements
Ensure `docker` & `docker compose` are installed on your server/system. Both are typically included with Docker utilities, like Docker Desktop and Rancher Desktop.
**Note**: `docker compose` without the hyphen is now the primary method of using docker-compose, according to the Docker documentation.
1. Clone the repository:
```bash
git clone https://github.com/formbricks/formbricks.git && cd formbricks
```
2. Modify the `.env.docker` file as required by your setup. This file comes with a basic setup and Formbricks works without making any changes to the file. To enable email sending functionality you need to configure the SMTP settings. If you configured your email credentials, you can also comment the following lines to enable email verification (`# NEXT_PUBLIC_EMAIL_VERIFICATION_DISABLED=1`) and password reset (`# NEXT_PUBLIC_PASSWORD_RESET_DISABLED=1`)
Note: All environment variables starting with `NEXT_PUBLIC_` are used at build time. When you change environment variables later, you need to rebuild the image with `docker compose build` for the changes to take effect.
3. Finally start the docker compose process to build and spin up the Formbricks container as well as the PostgreSQL database.
```bash
docker compose up -d
# (use docker-compose if you are on an older docker version)
```
You can now access the app on [http://localhost:3000](http://localhost:3000). You will be automatically redirected to the login. To use your local installation of Formbricks, create a new account.
Certainly, here is the reformatted version for Formbricks environment variables.
### Important Run-time Variables
These variables must also be provided at runtime.
| Variable | Description | Required | Default |
| --------------- | --------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------- |
| WEBAPP_URL | Base URL of the site. | required | `http://localhost:3000` |
| DATABASE_URL | Database URL with credentials. | required | `postgresql://postgres:postgres@postgres:5432/formbricks?schema=public` |
| NEXTAUTH_SECRET | Secret for NextAuth, used for session signing and encryption. | required | (Generated by the user) |
| NEXTAUTH_URL | Location of the auth server. By default, this is the Formbricks docker instance itself. | required | `http://localhost:3000` |
### Build-time Variables
These variables must be provided at the time of the docker build and can be provided by updating the `.env` file.
| Variable | Description | Required | Default |
| --------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------- | ----------------------- |
| NEXT_PUBLIC_WEBAPP_URL | Base URL injected into static files. | required | `http://localhost:3000` |
| PRISMA_GENERATE_DATAPROXY | Enables a dedicated connection pool for Prisma using Prisma Data Proxy. Uncomment to enable. | optional | |
| NEXT_PUBLIC_EMAIL_VERIFICATION_DISABLED | Disables email verification if set to `1`. | optional | |
| NEXT_PUBLIC_PASSWORD_RESET_DISABLED | Disables password reset functionality if set to `1`. | optional | |
| NEXT_PUBLIC_SIGNUP_DISABLED | Disables the ability for new users to create an account if set to `1`. | optional | |
| NEXT_PUBLIC_INVITE_DISABLED | Disables the ability for invited users to create an account if set to `1`. | optional | |
| NEXT_PUBLIC_PRIVACY_URL | URL for privacy policy. | optional | |
| NEXT_PUBLIC_TERMS_URL | URL for terms of service. | optional | |
| NEXT_PUBLIC_IMPRINT_URL | URL for imprint. | optional | |
| SENTRY_IGNORE_API_RESOLUTION_ERROR | Disables Sentry warning if set to `1`. | optional | |
| NEXT_PUBLIC_SENTRY_DSN | DSN for Sentry error tracking. | optional | |
| NEXT_PUBLIC_GITHUB_AUTH_ENABLED | Enables GitHub login if set to `1`. | optional | |
| GITHUB_ID | Client ID for GitHub. | optional (required if GitHub auth is enabled) | |
| GITHUB_SECRET | Secret for GitHub. | optional (required if GitHub auth is enabled) | |
| NEXT_PUBLIC_GOOGLE_AUTH_ENABLED | Enables Google login if set to `1`. | optional | |
| GOOGLE_CLIENT_ID | Client ID for Google. | optional (required if Google auth is enabled) | |
| GOOGLE_CLIENT_SECRET | Secret for Google. | optional (required if Google auth is enabled) | |
| CRON_SECRET | Secret for running cron jobs. | optional | |
Please refer to the [Formbricks Instructions](https://github.com/formbricks/formbricks) for more details on generating these variables.
## Debugging
If you encounter any issues, you can check the logs of the container with:
```bash
docker compose logs -f
```
You can close the logs again with `CTRL + C`.
## Troubleshooting for the Shell Script Setup
If you encounter any issues, consider the following steps:
- **Inbound Rules**: Make sure you have added inbound rules for Port 80 and 443 in your VM's Security Group.
- **A Record**: Verify that you have set up an A record for your domain, pointing to your VM's IP address.
- **Check Docker Instances**: Run `docker ps` to check the status of the Docker instances.
- **Check Formbricks Logs**: Run `cd formbricks && docker compose logs` to check the logs of the Formbricks stack.
apps/formbricks-com/app/docs/self-hosting/docker/page.mdx
+125
View File
@@ -0,0 +1,125 @@
export const meta = {
title: "Deploying Formbricks to production",
description:
"Utilize Docker-Compose for easy deployment on your machine. Clone the repo, configure settings, and build the image to access the app on localhost.",
};
[Self-hosting]()
# Running Formbricks with Docker
Quickly set up and start using Formbricks without getting into the technicalities of the build process. You'll be using an image that we've already built for you. The pre-built image is ready-to-run, and it only requires minimal configuration on your part. This approach is perfect for getting a functional instance of Formbricks up and running with minimal hassle. It's as easy as downloading the Docker image and firing up the container.
## We will be using the pre-built Formbricks Docker Image
This is ideal for those who are testing Formbricks or want to run it with minimal to no modifications. For this we use the [public Docker image](https://hub.docker.com/r/formbricks/formbricks) and a simple docker-compose file.
### Requirements
Ensure `docker` & `docker compose` are installed on your server/system. Both are typically included with Docker utilities, like Docker Desktop and Rancher Desktop.
<Note>
`docker compose` without the hyphen is now the primary method of using docker-compose, according to the
Docker documentation.
</Note>
1. **Create a New Directory for Formbricks**
Open a terminal and create a new directory for Formbricks, then navigate into this new directory:
<CodeGroup title="Create and cd into the new directory">
```bash
mkdir formbricks-quickstart && cd formbricks-quickstart
```
</CodeGroup>
2. **Download the Docker-Compose File**
Download the docker-compose file directly from the Formbricks repository:
<CodeGroup title="Download docker compose file">
```bash
curl -o docker-compose.yml https://raw.githubusercontent.com/formbricks/formbricks/main/docker/docker-compose.yml
```
</CodeGroup>
3. **Generate NextAuth Secret**
Next, you need to generate a NextAuth secret. This will be used for session signing and encryption. The `sed` command below generates a random string using `openssl`, then replaces the `NEXTAUTH_SECRET:` placeholder in the `docker-compose.yml` file with this generated secret:
<CodeGroup title="Generate NextAuth Secret">
```bash
sed -i "/NEXTAUTH_SECRET:$/s/NEXTAUTH_SECRET:.\*/NEXTAUTH_SECRET: $(openssl rand -base64 32)/" docker-compose.yml
```
</CodeGroup>
4. **Start the Docker Setup**
You're now ready to start the Formbricks Docker setup. The following command will start Formbricks together with a postgreSQL database using Docker Compose:
<CodeGroup title="Launch Docker Instance">
```bash
docker compose up -d
```
</CodeGroup>
The `-d` flag will run the containers in detached mode, meaning they'll run in the background.
5. **Visit Formbricks in Your Browser**
After starting the Docker setup, visit http://localhost:3000 in your browser to interact with the Formbricks application. The first time you access this page, you'll be greeted by a setup wizard. Follow the prompts to define your first user and get started.
## Updating Formbricks
1. Stop the Formbricks stack
<CodeGroup title="Stop the docker instance">
```bash
docker compose down
```
</CodeGroup>
2. Pull the latest changes
<CodeGroup title="Pull the changes into docker">
```bash
docker compose pull
```
</CodeGroup>
3. Update env vars as necessary.
4. Re-start the Formbricks stack
<CodeGroup title="Relaunch the Docker Instance">
```bash
docker compose up -d
```
</CodeGroup>
## Debugging
If you encounter any issues, you can check the logs of the container with:
<CodeGroup title="Look into docker logs">
```bash
docker compose logs -f
```
</CodeGroup>
You can close the logs again with `CTRL + C`.
apps/formbricks-com/app/docs/self-hosting/from-source/page.mdx
+98
View File
@@ -0,0 +1,98 @@
export const meta = {
title: "Deploying Formbricks to production",
description:
"Utilize Docker-Compose for easy deployment on your machine. Clone the repo, configure settings, and build the image to access the app on localhost.",
};
[Self-hosting]()
# Deploying Formbricks to production
This approach provides the flexibility to configure every aspect of your Formbricks instance, including environment variables that need to be set at build time. While we don't recommend changing the source code of Formbricks, this method allows you to set your own configuration that might be necessary for specific deployment needs. Keep in mind that this method requires a more in-depth understanding of Docker and the build process. However, the trade-off is the additional control and flexibility you gain, making it worth considering if you're a more advanced user or have very specific configuration needs.
### Requirements
Ensure `docker` & `docker compose` are installed on your server/system. Both are typically included with Docker utilities, like Docker Desktop and Rancher Desktop.
<Note>
`docker compose` without the hyphen is now the primary method of using docker-compose, according to the
Docker documentation.
</Note>
1. **Clone the repository**:
<CodeGroup title="Clone and cd into the Formbricks directory">
```bash
git clone https://github.com/formbricks/formbricks.git && cd formbricks
```
</CodeGroup>
2. **Modify the `.env.docker` file as required by your setup.** <br/> This file comes with a basic setup and Formbricks works without making any changes to the file. To enable email sending functionality you need to configure the SMTP settings. If you configured your email credentials, you can also comment the following lines to enable email verification (`# NEXT_PUBLIC_EMAIL_VERIFICATION_DISABLED=1`) and password reset (`# NEXT_PUBLIC_PASSWORD_RESET_DISABLED=1`)
<Note>
Note: All environment variables starting with `NEXT_PUBLIC_` are used at build time. When you change
environment variables later, you need to rebuild the image with `docker compose build` for the changes
to take effect.
</Note>
3. **Start the docker compose process.** <br/> Finally start the docker compose process to build and spin up the Formbricks container as well as the PostgreSQL database. <br/> _Use docker-compose if you are on an older docker version_
<CodeGroup title="Launch docker instances">
```bash
docker compose up -d
```
</CodeGroup>
You can now access the app on [http://localhost:3000](http://localhost:3000). You will be automatically redirected to the login. To use your local installation of Formbricks, create a new account.
### Important Run-time Variables
These variables must also be provided at runtime.
| Variable | Description | Required | Default |
| --------------- | --------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------- |
| WEBAPP_URL | Base URL of the site. | required | `http://localhost:3000` |
| DATABASE_URL | Database URL with credentials. | required | `postgresql://postgres:postgres@postgres:5432/formbricks?schema=public` |
| NEXTAUTH_SECRET | Secret for NextAuth, used for session signing and encryption. | required | (Generated by the user) |
| NEXTAUTH_URL | Location of the auth server. By default, this is the Formbricks docker instance itself. | required | `http://localhost:3000` |
### Build-time Variables
These variables must be provided at the time of the docker build and can be provided by updating the `.env` file.
| Variable | Description | Required | Default |
| --------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------- | ----------------------- |
| NEXT_PUBLIC_WEBAPP_URL | Base URL injected into static files. | required | `http://localhost:3000` |
| PRISMA_GENERATE_DATAPROXY | Enables a dedicated connection pool for Prisma using Prisma Data Proxy. Uncomment to enable. | optional | |
| NEXT_PUBLIC_EMAIL_VERIFICATION_DISABLED | Disables email verification if set to `1`. | optional | |
| NEXT_PUBLIC_PASSWORD_RESET_DISABLED | Disables password reset functionality if set to `1`. | optional | |
| NEXT_PUBLIC_SIGNUP_DISABLED | Disables the ability for new users to create an account if set to `1`. | optional | |
| NEXT_PUBLIC_INVITE_DISABLED | Disables the ability for invited users to create an account if set to `1`. | optional | |
| NEXT_PUBLIC_PRIVACY_URL | URL for privacy policy. | optional | |
| NEXT_PUBLIC_TERMS_URL | URL for terms of service. | optional | |
| NEXT_PUBLIC_IMPRINT_URL | URL for imprint. | optional | |
| SENTRY_IGNORE_API_RESOLUTION_ERROR | Disables Sentry warning if set to `1`. | optional | |
| NEXT_PUBLIC_SENTRY_DSN | DSN for Sentry error tracking. | optional | |
| NEXT_PUBLIC_GITHUB_AUTH_ENABLED | Enables GitHub login if set to `1`. | optional | |
| GITHUB_ID | Client ID for GitHub. | optional (required if GitHub auth is enabled) | |
| GITHUB_SECRET | Secret for GitHub. | optional (required if GitHub auth is enabled) | |
| NEXT_PUBLIC_GOOGLE_AUTH_ENABLED | Enables Google login if set to `1`. | optional | |
| GOOGLE_CLIENT_ID | Client ID for Google. | optional (required if Google auth is enabled) | |
| GOOGLE_CLIENT_SECRET | Secret for Google. | optional (required if Google auth is enabled) | |
| CRON_SECRET | Secret for running cron jobs. | optional | |
Please refer to the [Formbricks Instructions](https://github.com/formbricks/formbricks) for more details on generating these variables.
## Debugging
If you encounter any issues, you can check the logs of the container with:
```bash
docker compose logs -f
```
You can close the logs again with `CTRL + C`.
apps/formbricks-com/app/docs/self-hosting/production/page.mdx
+63
View File
@@ -0,0 +1,63 @@
export const meta = {
title: "Deploying Formbricks to production",
description:
"Utilize Docker-Compose for easy deployment on your machine. Clone the repo, configure settings, and build the image to access the app on localhost.",
};
[Self-hosting]()
# Deploying Formbricks to Production
If you want to quickly set up a production instance of Formbricks on a server running Ubuntu, we've got you covered! This method utilizes a convenient shell script that takes care of everything, including Docker, Postgres DB, and SSL certificate configuration. The shell script will automatically install all the required dependencies and configure your server, making the process a breeze.
## One-click Ubuntu setup with our Shell Script
This is the quickest way to get Formbricks up and running on an Ubuntu server. The shell script will automatically install all the required dependencies and configure your server, making the process a breeze.
### Requirements
Before you proceed, make sure you have the following:
- A Linux Ubuntu Virtual Machine deployed with SSH access.
- An **A record** set up to connect a custom domain to your instance. Formbricks will **automatically create an SSL certificate** for your domain using Let's Encrypt.
## Single Command Setup
Copy and paste the following command into your terminal:
```bash
/bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/formbricks/formbricks/main/docker/production.sh)"
```
The script will prompt you for the following information:
1. **Overwriting Docker GPG Keys**: If Docker GPG keys already exist, the script will ask if you want to overwrite them.
2. **Email Address**: Provide your email address for SSL certificate registration with Let's Encrypt.
3. **Domain Name**: Enter the domain name that Traefik will use to create the SSL certificate and forward requests to Formbricks.
That's it! After running the command and providing the required information, visit the domain name you entered, and you should see the Formbricks home wizard!
## Debugging
If you encounter any issues, you can check the logs of the container with:
```bash
docker compose logs -f
```
You can close the logs again with `CTRL + C`.
## Troubleshooting
If you encounter any issues, consider the following steps:
- **Inbound Rules**: Make sure you have added inbound rules for Port 80 and 443 in your VM's Security Group.
- **A Record**: Verify that you have set up an A record for your domain, pointing to your VM's IP address.
- **Check Docker Instances**: Run `docker ps` to check the status of the Docker instances.
- **Check Formbricks Logs**: Run `cd formbricks && docker compose logs` to check the logs of the Formbricks stack.
apps/formbricks-com/components/docs/Navigation.tsx
+6 -1
View File
@@ -267,7 +267,12 @@ export const navigation: Array<NavGroup> = [
},
{
title: "Self-hosting",
links: [{ title: "Deployment", href: "/docs/self-hosting/deployment" }],
links: [
{ title: "Deployment", href: "/docs/self-hosting/deployment" },
{ title: "Production", href: "/docs/self-hosting/production" },
{ title: "Docker", href: "/docs/self-hosting/docker" },
{ title: "From Source", href: "/docs/self-hosting/from-source" },
],
},
{
title: "Contributing",