This repo has been mostly superceded by an alternative terraform approach - see https://docs.digitalocean.com/developer-center/hosting-supabase-on-digitalocean/ for details. Although that guide is specifically for hosting on DigitalOcean, the core practices it demonstrates should apply to most other cloud providers.
This repo includes an example of starting a local copy of the Supabase stack via Terraform. At this time, it does not support deployment to a remote VPS.
This repo is still a work in progress - it should NOT be used for production deployments at this time. For example, the Terraform configuration currently created will destroy all volumes when destroy
is called. You WILL lose all data.
Known issues such as this will be resolved in due course.
Please note that your Postgres password, JWT secret and JWT tokens are automatically generated during setup. If you are using the Watchtower plugin, the HTTP API token for that is also automatically generated. In order to retrieve these values for use in an application:
- Your
anon_key
andservice_role_key
can be found in thekong_data
docker volume, inside thekong.yml
file - Your
jwt_secret
can be found in the environmental variables of thesupabase-auth
docker container - Your
postgres_password
can be found in the environmental variables of thedb
docker container - If you have enabled the Watchtower plugin, you can find your HTTP API token in the environmental variables of the
watchtower
docker container
As of writing, these values are not output to the terminal or disk as they are considered very sensitive.
The Postgres password is 96 characters in length, while the JWT secret is 64 characters in length. The watchtower HTTP API token is 128 characters in length.
- Install docker - instructions at https://docs.docker.com/get-docker/
- Install the Terraform CLI - instructions at https://www.terraform.io/downloads
- Rename
./supabase/definitions/dotenv.tf.example
to./supabase/definitions/dotenv.tf
a. This file includes the sensitive Supabase-related environment variables (except for third-party auth variables) b. You should never commit this file to git -dotenv.tf
is already included in.gitignore
- Rename
./plugins/defintions/dotenv.tf.example
to./plugins/definitions/dotenv.tf
a. This file includes all sensitive plugin-related environment variables b. It should never be commited to git - Rename
./supabase/definitions/thirdpartyauth.dotenv.tf.example
to./supabase/definitions/thirdpartyauth.dotenv.tf
a. This file is where all third-party auth variables should be set b. You should never commit this file to git -thirdpartyauth.dotenv.tf
is already in.gitignore
, so unless you use a different filename, change the gitignore or place the variables in a different file, you won't accidentally leak your secrets - Run
terraform init
from the folder where this readme is located - Run
terraform plan
from the folder where this readme is located - Run
terraform apply
and typeyes
when prompted
To stop the stack, type terraform destroy
and type yes
when prompted.
If there are any errors, please, please, please read what the terminal outputs as it will often tell you how to resolve the issue.
If you're still having trouble, you can remove the Terraform dependencies and packages by removing the following from your copy of this repo:
.terraform/
folderterraform.tfstate
fileterraform.tfstate.backup
fileterraform.lock.hcl
file
This repo provides a 'plugin' system which allows you to add some common Docker images and containers to the project.
Inside the ./plugins/definitions
folder, you will find a provider.tf
file. This file is where you can control which plugins are enabled.
Plugin secret environmental variables can be set in./plugins/definitions/dotenv.tf.example
. Rename to dotenv.tf
before attempting to run terraform
commands.
For example, there is a USE_PORTAINER
variable block. Inside this block, there is a default
field. By setting the value of this field to true
, you will enable the download and provisioning of the Portainer image and container.
- Current plugins
- Portainer (disabled by default)
- Main plugin file:
./plugins/definitions/WithPortainer.tf
- Main plugin file:
- Nginx (disabled by default)
- This plugin is already configured for use with Supabase
- Main plugin file:
./plugins/definitions/WithNginx.tf
- All variables for Nginx are stored in this file
- You should ensure you read the comments left in that file if you intend to use this plugin
- Watchtower (disabled by default)
- Main plugin file:
./plugins/definitions/WithWatchtower.tf
- Environment variable options: https://containrrr.dev/watchtower/arguments/
- HTTP API (to trigger image and container updates): https://containrrr.dev/watchtower/http-api-mode/
- The HTTP API token for watchtower is a 128-character random password
- Main plugin file:
- Portainer (disabled by default)
In essence, plugins are simply docker containers that will be initialized and included during setup.
First, you need to ensure that it is possible to toggle the plugin. To do this, add a new variable
block in ./plugins/definitions/provider.tf
;
variable "USE_PLUGIN" {
type = bool
default = false
description = "Set default to true if you want to add <Plugin name> to the deployment"
}
You should ensure that the default
is set to false - all plugins are considered optional, but disabled by default.
Then create a new file with a .tf
extension in the ./plugins/definitions
folder. This file should be named With<Plugin>.tf
(replace <plugin>
with the name of your plugin).
Add your Docker images and containers as resources:
resource "docker_image" "plugin" {
name = "myorganisation/plugin:latest"
keep_locally = true
count = var.USE_PLUGIN ? 1 : 0
}
resource "docker_container" "plugin" {
count = var.USE_PLUGIN ? 1 : 0
image = "myorganisation/plugin:latest"
name = "plugin"
ports {
internal = 11111
external = 11111
}
}
The above is just an example!
The most important part is ensuring that the count
property of all resources is set to 1
if your variable is true
, and 0
if it is false
.
If your container requires any secret environmental variables, place them in ./plugins/defintions/dotenv.tf
. Any non-secret variables should be stored in the same file as the plugin.
You should also ensure that you add the same variables to the ./plugins/definitions/dotenv.tf.example
file but ensure you remove the secret value before you commit the file!
This repo allows you to customise the postgresql.conf
file before deployment. The default config provided within the Supabase docker image (as of 28th February 2022) is included at ./volumes/db/config/postgresql.conf
. The default config should be sufficient, but feel free to adjust this according to your requirements.
Also included is the kong.yml
config file used by Kong - available at ./volumes/api/kong.tpl
. This is a Terraform template file, meaning that it includes some template variables which are replaced during deployment:
${META_URL}
- The URL which docker containers can access thepg-meta
container at${META_PORT}
- The port which thepg-meta
container is running on${ANON_KEY}
- The Supabase anon key${SECRET_KEY}
- The supabase service role key
These variables are passed into the template from docker.containers.tf
and should not be modified. If you want to change any of these value, change them in the dotenv.tf
file (see instructions section above for details).
The reason for using a template file is that it allows us to keep the environmental variables secret, while also avoiding the need to change them in more than one place. With the normal docker-compose deployment, you have to change some env variables in kong.yml
as well as in the .env
file.