Connections

Connection guides

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.

GitHub repository

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.

‣

AWS EC2

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 and 5000, with sources set to Anywhere ( 0.0.0.0/0 and ::/0), and click Review and Launch. We need to open ports 80 (http) and 443 (https) so you can connect to the server from a browser, as well as port 22 (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 port 5000.

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.

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.

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 the docker_compose.yml file and in the nginx/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 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 the docker-compose.yml file to replace --staging with --force-renewal. In the nginx/app.conf file, remove the proxy_pass location block in the first server block and uncomment out the SSL related configuration.
Start the app again using sudo docker-compose up -d

Creating an S3 bucket

Next, create two S3 buckets: one for images and one for any SSH and SSL keys. The images bucket should have public access unblocked, while the ssh/ssl key bucket should have public access blocked.

AWS S3 dashboard

‣

AWS ECS

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 templace 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.

‣

Google Cloud Platform

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 the docker-compose.yml file (1 case) and in the nginx/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 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 the docker-compose.yml file to replace --staging with --force-renewal. In the nginx/app.conf file, remove the proxy_pass location block in the first server 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.

📢

Remember to whitelist the Basedash server's IP on your database host so your database allows connections from the Basedash app.

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.

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.

AWS_SECRET_ACCESS_KEY

AWS secret access key. See AWS documentation on how to retrieve this value.

BUCKET_ENDPOINT

S3 (or digital ocean) bucket endpoint

BUCKET_NAME

The name of your S3 storage bucket.

BUCKET_NAME_IMAGES

This should be equal to your value for BUCKET_NAME. This environment variable won't be required in a future release.

BUCKET_NAME_KEYS

This should be equal to your value for BUCKET_NAME. This environment variable won't be required in a future release.

BASE_URL

The domain of the web application. Used for the links in Slack notifications and login magic links.

example: https://app.basedash.com

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

DATABASE_HOST

Host for postgres database.

default: localhost

DATABASE_NAME

Postgres database name

default: basedash

DATABASE_PASSWORD

Postgres database password

DATABASE_PORT

Postgres database port

default: 5432

DATABASE_USERNAME

Postgres database username

default: postgres

JWT_KEY

A random string of characters used for signing JWTs

example: eake23i1ij82ajhdbe965

NODE_ENV

Should be set to production.

SENDGRID_API_KEY

Used for all emails in the app, including the email verification during signup.

If this isn’t setup, then you will not receive emails from Basedash for things like user signups/invitations. Only the Basedash team can provide you with an SendGrid API key.

You’ll need to create your own Sengrid account and create a new API key.

When configuring the new API key, set Restricted Access, and make sure the following permissions are enabled.

AUTHY_API_KEY

Authy is the two factor authentication provider used for the Basedash app. Read the authy documentation on how to get an API key. You will have to create an Authy/Twilio account in order to create an authy app and generate an API key.

If this is not setup, you will not be able to have two-factor authentication in Basedash. Only the Basedash team can provide you with an SendGrid API key.