Connection guides
Integrations
Self-hosting
Have full control of your data by self-hosting Basedash on your own servers.
Enterprise users may choose to run a self-hosted version of Basedash for privacy and security reasons.
GitHub repository
There is a GitHub repository that contains all of the setup code. This code will be copied into a server using a git clone
command and then you will be able to run scripts that will help setup the server to run Basedash.
Setup instructions
We have detailed setup instructions for AWS and GCP. However, it should be possible to host Basedash on any hosting provider that supports Docker.
- Launch a new instance of EC2 in the AWS dashboard
- Select an Ubuntu server
- Select a
t3.medium
or higher and click Next - Select the VPC under Network that contains any database and/or APIs the Basedash server should be able to connect to and click Next
- Increase your storage size to 40 GB or higher and click Next
- Optionally add some Tags (e.g.
app = basedash
) and click Next. This makes it easier to find if you have a lot of instances. - Set the network security groups for ports
80
,443
,22
and5000
, with sources set to Anywhere (0.0.0.0/0
and::/0
), and click Review and Launch. We need to open ports80
(http) and443
(https) so you can connect to the server from a browser, as well as port22
(ssh) so that you can ssh into the instance to configure it and run Basedash. By default on a vanilla EC2, Basedash will run on port5000
. - On the Review Instance Launch screen, click Launch to start your instance.
- Create a new SSH key pair (or use an existing one), and download the it. This will be used to SSH into the EC2 instance.
- If you're connecting to internal databases, whitelist the VPS's IP address in your database.
- From your command line tool, SSH into your EC2 instance. You'll need to use the SSH
.pem
file you've downloaded. See screenshot for instructions. - SSH into your instance.
- Clone the
basedash/self-hosted
repo:git clone https://github.com/Basedash/self-hosted.git
. Make sure your instance can connect to the internet (e.g. might need to hook up public IP address to your instance with Elastic IP). - Run the install scripts:
cd ./self-hosted && ./
install.sh
- Replace
basedash.fm
in thedocker_compose.yml
file and in thenginx/app.conf
file. Also, make sure to use your valid email address for the certbot command. - Make sure to create an
A
record for your basedash subdomain pointing towards you basedash server's IP address. This is required in order for Let's Encrypt to issue SSL certificates. - Run migrations using
sudo docker-compose run --workdir /app/packages/prisma app yarn prisma migrate deploy
- Start the app with docker-compose:
sudo docker-compose up
. Make sure the logs show that the SSL certificates have been generated. - Stop the
docker-compose
process and modify thedocker-compose.yml
file to replace--staging
with--force-renewal
. In thenginx/app.conf
file, remove theproxy_pass
location block in the firstserver
block and uncomment out the SSL related configuration. - Start the app again using
sudo docker-compose up -d
You might have a different mechanism for passing your SSH keys (e.g. a jump proxy) or you might re-use a key pair that you've already created for your VPC.
Creating an S3 bucket
Next, create an S3 bucket with public access unblocked. The S3 bucket will be used to store images and connection files.
- Create a new ECS cluster in the AWS dashboard.
- Select EC2 Linux + Network
- Instance configuration:
- On-demand instance
- t3.medium EC2 instances
- Desired number of instances
- Default EC2 AMI ID
- Default EBS volume size
- Select a key pair if you want to be able to SSH to instances
- Networking configuration:
- Select an existing VPC or create a new one.
- Select a public subnet (Public subnets have a default route (
0.0.0.0/0
) pointing to an internet gateway) - Use subnet settings to auto assign public IP
- Select a security group that has the same rules described in the AWS EC2 setup instructions.
- Enable cloudwatch logs
- Download the cloudformation template in the cloned repo (basedash.yml)
- Go to the cloudformation dashboard and create a new stack from new ressources and upload the cloudformation template
- Input the parameters required for the cloudformation template and then finalize the creation of the stack.
- Navigate to the Compute Engine VM instances page.
- Create a new instance
- Set a name
- Choose a region
- Select an
e2-medium
machine - Change the boot disk to use an Ubuntu server an set the size to 40 GB
- Allow HTTP and HTTPS traffic in the firewall settings
- SSH into server
- Clone the
basedash/self-hosted
repo:git clone https://github.com/Basedash/self-hosted.git
- Run the install scripts:
cd ./self-hosted && ./install.sh
- Populate the
docker.env
file with all required environment variables. - Replace
basedash.fm
in thedocker-compose.yml
file (1 case) and in thenginx/app.conf
file (4 cases). Also, make sure to use your valid email address for the certbot command. - Make sure to create an
A
record for your basedash subdomain pointing towards you basedash server's IP address. This is required in order for Let's Encrypt to issue SSL certificates. - Run migrations using
sudo docker-compose up -d db && sudo docker-compose run --workdir /app/packages/prisma app yarn prisma migrate deploy
- Start the app with docker-compose:
sudo docker-compose up
. Make sure the logs show that the SSL certificates have been generated. - Stop the
docker-compose
process and modify thedocker-compose.yml
file to replace--staging
with--force-renewal
. In thenginx/app.conf
file, remove theproxy_pass
location block in the firstserver
block and uncomment out the SSL related configuration. - Start the app again using
sudo docker-compose up -d
Slack notifications
You’ll need to create a new Slack app, provide the chat:write
scope to the bot, and then use the provided client ID and client secret as environment variables to the Docker image.
You’ll also need to add a Redirect URL to your slack app config that corresponds with the URL of your self-hosted basedash app. Note, your app must be hosted on HTTPS for this to work.
Renewing SSL certificates
You can manually update the certificates by running the following commands from the self-hosted
directory:
docker-compose run certbot
docker-compose restart nginx
Read this article on how to use cron jobs with certbot to automatically renew SSL certificates.
Upgrading Basedash versions
Simply run the update.sh
script from the self-hosted
directory.
Database
The current self-hosted setup creates a local postgres database using docker on the self-hosted server. The database data is persisted to the server through a docker volume. If you'd like to use a database hosted elsewhere, you should be able to do an SQL dump of the docker database, import the SQL dump to another database, and change the environment variables related to the database credentials. Restart the server using docker-compose up -d --force-recreate
and then the app should be using the new database.
Environment variables
The following are all the available environment variables that can be used to configure Basedash. The values can be added and modified in the docker.env
file.
BASEDASH_LICENSE_KEY
Required to run the app. Provided by the Basedash team.
Required
AWS_ACCESS_KEY_ID
AWS access key. See AWS documentation on how to retrieve this value.
We recommend creating a new IAM user with All S3 actions
enabled for the S3 bucket.
Required
AWS_SECRET_ACCESS_KEY
AWS secret access key. See AWS documentation on how to retrieve this value.
Required
BUCKET_ENDPOINT
S3 (or digital ocean) bucket endpoint
Required
BUCKET_NAME_IMAGES
This should be equal to your value for BUCKET_NAME
. This environment variable won't be required in a future release.
Required
BUCKET_NAME_KEYS
This should be equal to your value for BUCKET_NAME
. This environment variable won't be required in a future release.
Required
BASE_URL
The domain of the web application. Used for the links in Slack notifications and login magic links.
example: https://app.basedash.com
Required
CRYPTO_KEY
A random string of characters used when hashing passwords for storage in the database. Randomly generated from the self-hosted setup script. Needs to be 32 characters in length.
example: &E(H+MbQeThWmZq4t7w!z%C*F-J@NcRf
Required
POSTGRES_HOST
Host for postgres database.
Required
POSTGRES_DB
Postgres database name
Required
POSTGRES_PASSWORD
Postgres database password
Required
POSTGRES_PORT
Postgres database port
Required
POSTGRES_USER
Postgres database username
Required
POSTGRES_SSL_CA_CERT
Certificate authority (CA) certificate associated with postgres database. Used for SSL database connections and only necessary for apps that want to enable SSO and have their database SSL protected.
RESEND_API_KEY
Used for transactional emails in the app, including email verification during signup.
Required
TWILIO_ACCOUNT_SID
TWILIO_AUTH_TOKEN
TWILIO_VERIFY_SERVICE_SID
Twilio is the SMS two factor authentication provider used for the Basedash app.
If this is not setup, you will not be able to have two-factor authentication in Basedash. The Basedash team can provide you with a Twilio API key.
SLACK_CLIENT_ID
Used to enable Slack notifications on views. Note that your app must be accessible via HTTPS in order for this to work.
If this is not setup, you will not be able to enable Slack notifications.
SLACK_CLIENT_SECRET
Used to enable Slack notifications on views. Note that your app must be accessible via HTTPS in order for this to work.
If this is not setup, you will not be able to enable Slack notifications.
GOOGLE_OAUTH_CLIENT_ID
Used for “Sign in with Google”. Note that your app must be accessible via HTTPS in order for this to work.
If this is not setup, you will not be able to login/signup with Google.
OPENAI_API_KEY
Used for various AI features across the app, such as generated values and “Ask AI”.
The Basedash team can provide you with an OpenAI API key if you do not have one.
INTERCOM_APP_ID
Used to have intercom chat support with the Basedash team.
LOG_LEVEL
Controls the minimum level of logs outputted to the console. Can be one of 'error', 'warn', 'info', 'http', 'verbose', 'debug', or 'silly'.
default: info
ENABLE_HTTP_LOGS
Used if you'd like to get logs for every HTTP request made to the server.
default: false
DEBUG_SQL
Outputs SQL errors to the console. Useful for debugging SQL errors, even when in production.
default: false
ENABLE_SQL_LOGGING
Will log out all SQL queries made to databases connected to Basedash.
default: false
RABBITMQ_URL
URL of the RabbitMQ service. Defaults to URL of a RabbitMQ service running via docker-compose.
default: amqp://localhost:5672
Version number
You can identify the version number of your self-hosted Basedash instance by inspecting the HTML of your Basedash app and looking for the <meta name="version" content="XXX">
tag.
This version should correspond with a docker image tag found on docker hub (https://hub.docker.com/repository/docker/basedash/basedash/tags?page=1&ordering=last_updated).