https://github.com/supabase-community/supabase-terraform

https://github.com/supabase-community/supabase-terraform

Last synced: about 2 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/supabase-community/supabase-terraform
• Owner: supabase-community
• Created: 2022-03-21T14:43:28.000Z (about 3 years ago)
• Default Branch: main
• Last Pushed: 2023-02-07T18:04:58.000Z (about 2 years ago)
• Last Synced: 2025-02-13T20:33:47.829Z (about 2 months ago)
• Language: HCL
• Size: 43.9 KB
• Stars: 97
• Watchers: 13
• Forks: 9
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

• jimsghstars - supabase-community/supabase-terraform - (HCL)

README

        
# Note #

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.

# Terraform Supabase

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.

### Very important notice

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.

### Secure values

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` and `service_role_key` can be found in the `kong_data` docker volume, inside the `kong.yml` file

- Your `jwt_secret` can be found in the environmental variables of the `supabase-auth` docker container

- Your `postgres_password` can be found in the environmental variables of the `db` 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.

### Instructions

1. Install docker - instructions at https://docs.docker.com/get-docker/

2. Install the Terraform CLI - instructions at https://www.terraform.io/downloads

3. 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`

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

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

6. Run `terraform init` from the folder where this readme is located

7. Run `terraform plan` from the folder where this readme is located

8. Run `terraform apply` and type `yes` 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/` folder

- `terraform.tfstate` file

- `terraform.tfstate.backup` file

- `terraform.lock.hcl` file

### Plugins

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`

  - 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

### Adding a new plugin

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  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.tf` (replace `` 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**!

### Additional information

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 the `pg-meta` container at

- `${META_PORT}` - The port which the `pg-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.