Plane DocsSign in

Configure external services Commercial Edition ​

The Prime CLI lets you easily configure your Commercial Edition instance, providing options to customize the PostgreSQL database, Redis, external storage, and other advanced settings.

WARNING

Prime CLI is for Docker installations only. These commands only work on Plane instances originally installed using prime-cli.

  1. Run the Prime CLI with ↓:

sudo prime-cli

  1. Once the CLI is running, enter configure, which will guide you through a step-by-step form where you can specify the following:

  • Listening port
    Define the port for the built-in reverse proxy.
    Default: 80

  • Max file-upload size
    Set the maximum file size (in MB) that members can upload. Default: 5 MB

  • External Postgres URL
    Provide the URL of your external PostgreSQL instance if you want to switch from the default Plane configuration. Default: Postgres 15.5 in the Docker container.

WARNING

Don’t use a database on your local machine. If you use localhost in the URL, it won’t work. Make sure to use a database hosted on a network-accessible server.

Avoid using special characters in your PostgreSQL password.

  • External Redis URL
    Specify the URL of your external Redis instance to override the default Redis configuration. Turn on keyspace notifications on it first.
    Default: Redis 7.2.4

  • External storage
    Plane currently supports only S3 compatible storages.
    Default: MinIO

    1. Ensure your IAM user has the following permissions on your S3 bucket.
    • s3:GetObject
      To access the objects.
    • s3:PutObject
      To upload new assets using the presigned url.
    1. Configure the CORS policy on your bucket to enable presigned uploads. Use the example policy below, making sure to replace <YOUR_DOMAIN> with your actual domain.
    [
      {
         "AllowedHeaders": [
            "*"
         ],
         "AllowedMethods": [
            "GET",
            "POST",
            "PUT",
            "DELETE",
            "HEAD"
         ],
         "AllowedOrigins": [
            "<YOUR_DOMAIN>",
         ],
         "ExposeHeaders": [
            "ETag",
            "x-amz-server-side-encryption",
            "x-amz-request-id",
            "x-amz-id-2"
         ],
         "MaxAgeSeconds": 3000
      }
]
    1. Switch to your external storage by providing the following values:
      • S3 access key ID 
      • S3 secret access key
      • S3 bucket name
      • S3 region 
      • S3 endpoint URL
  1. After confirming your choices, your instance will automatically restart with the updated configuration.

Redis keyspace notifications ​

Plane's integrations service, silo, needs Redis to publish an event when a key expires. Silo uses these events to process the webhooks it receives for its GitHub, GitLab, Bitbucket, Slack, Sentry, Microsoft Teams and Pylon integrations.

With the Redis that Plane installs, you don't need to do anything, because silo turns the events on when it starts. Managed services such as Amazon ElastiCache block the CONFIG command silo uses for that, so on an external Redis you have to turn them on yourself.

Nothing fails when they're off

The integrations keep accepting webhooks but never act on them, so changes stop syncing between Plane and those tools. The only sign is a warning in the silo logs at startup: [Redis] Could not enable keyspace notifications.

Set the notify-keyspace-events parameter to Ex. If it already has a value, keep it and make sure it contains both E and x (A counts as x).

Amazon ElastiCache ​

You can't edit a default parameter group, so create one for your engine version, set the parameter on it, and assign it to the cluster. Use the family that matches your cluster, such as valkey8 or redis7. If the cluster already has a custom parameter group, set the parameter there instead.

bash
aws elasticache create-cache-parameter-group \
  --cache-parameter-group-name plane-redis \
  --cache-parameter-group-family valkey8 \
  --description "Plane: keyspace notifications"

aws elasticache modify-cache-parameter-group \
  --cache-parameter-group-name plane-redis \
  --parameter-name-values ParameterName=notify-keyspace-events,ParameterValue=Ex

aws elasticache modify-replication-group \
  --replication-group-id <your-replication-group> \
  --cache-parameter-group-name plane-redis \
  --apply-immediately

notify-keyspace-events is a dynamic parameter, so it takes effect without a reboot.

Google Cloud Memorystore for Redis ​

bash
gcloud redis instances update <instance> --region=<region> \
  --update-redis-config=notify-keyspace-events=Ex

Azure Cache for Redis ​

In the Azure portal, open the cache, go to Advanced settings, and set Keyspace notifications to Ex.

Self-managed Redis or Valkey ​

Add notify-keyspace-events Ex to redis.conf (or valkey.conf) and restart Redis. To change it without a restart, run CONFIG SET notify-keyspace-events Ex and then CONFIG REWRITE so the setting survives the next restart.

Check that it works ​

This uses only commands that managed services allow. Run the first command, and leave it running:

bash
redis-cli -u "$REDIS_URL" PSUBSCRIBE '__keyevent@*__:expired'

In a second terminal, create a key that expires after one second:

bash
redis-cli -u "$REDIS_URL" SET plane-keyspace-check 1 EX 1

Within a few seconds the first terminal prints plane-keyspace-check. If nothing arrives, the notifications are still off. Add --tls to both commands if your URL starts with rediss://.

Community Edition

To configure external Postgres, Redis, and S3 storage for the Plane Community Edition, you’ll need to adjust several environment variables in the plane.env file. Follow this guide to set up each component using the correct values for your external services.

  1. Open the plane.env file on your server where Plane is installed.

  2. In the DB SETTINGS section, update the variables to connect to your external Postgres instance:

    bash
    # DB SETTINGS
PGHOST=your-external-postgres-host          # Replace with the hostname or IP address of your Postgres server.
PGDATABASE=                                 # Leave blank when using external database.
POSTGRES_USER=your-postgres-username        # The username to access Postgres.
POSTGRES_PASSWORD=your-postgres-password    # Password for the Postgres user.
POSTGRES_DB=your-database-name              # The name of the database Plane should connect to.
POSTGRES_PORT=5432                          # Port where Postgres is accessible (usually 5432).
PGDATA=/var/lib/postgresql/data             # No need to change this for external Postgres.
DATABASE_URL=                               # Leave this empty if you're providing values for the variables above. If you choose to use the DATABASE_URL, you can leave all the other database-related variables empty.

    WARNING

    Don’t use a database on your local machine. If you use localhost in the URL, it won’t work. Make sure to use a database hosted on a network-accessible server.

    Avoid using special characters in your PostgreSQL password.

  3. In the REDIS SETTINGS section, update the variables to connect to your external Redis instance:

    bash
    # REDIS SETTINGS
REDIS_HOST=your-external-redis-host         # Hostname or IP of the Redis server.
REDIS_PORT=6379                             # Port where Redis is accessible (default is 6379).
REDIS_URL=                                  # Leave this empty if you're providing values for the variables above. If you choose to use the REDIS_URL, you can leave all the other redis-related variables empty.

  4. In the DATA STORE SETTINGS section, update the variables for any S3-compatible storage:

    bash
    # DATA STORE SETTINGS
USE_MINIO=0                                 # Set to 0 if using an external S3, 1 if using MinIO (default).
AWS_REGION=your-s3-region                   # For AWS, set the region, e.g., "us-west-1".
AWS_ACCESS_KEY_ID=your-s3-access-key        # Access key for S3.
AWS_SECRET_ACCESS_KEY=your-s3-secret-key    # Secret key for S3.
AWS_S3_ENDPOINT_URL=https://your-s3-endpoint # URL for S3 API endpoint (e.g., "https://s3.amazonaws.com" for AWS).
AWS_S3_BUCKET_NAME=your-s3-bucket-name      # Name of the S3 bucket for storing Plane data.
MINIO_ROOT_USER=                            # Leave blank when using external S3.
MINIO_ROOT_PASSWORD=                        # Leave blank when using external S3.
BUCKET_NAME=                                # Leave blank when using external S3.
FILE_SIZE_LIMIT=5242880                     # Set maximum file upload size in bytes (5MB here).

    TIP

    Running Plane on Amazon EKS with the Helm charts instead? You can leave the access key and secret out altogether and let Plane assume an IAM role. See Use IRSA or EKS Pod Identity for S3 storage.

  5. Save your changes to the plane.env file.

  6. Restart Plane services to apply the new settings using the setup.sh script.