Running Plane From a Custom Artifact Registry

Plane is a versatile open-source project management platform that many teams rely on for organizing tasks and improving collaboration. Yet, maintaining and customizing a self-hosted Plane instance requires careful planning, especially when upgrading or adapting it to specific requirements.

This article covers how to upgrade Plane. It explains how to work with specific versions of Plane. It also details how to use a custom Docker registry for Plane Docker images. We’ll also examine the benefits and downsides of this approach.

Upgrading a Self-Hosted Instance of Plane

Upgrading Plane ensures access to the latest features, performance enhancements, and security patches. Using the provided setup.sh script simplifies the process for self-hosted environments.

Backup Your Plane Instance

Always create a backup of your Plane database before an upgrade!

docker exec -i plane-db-container /bin/bash -c "PGPASSWORD=password pg_dump --username username dbName" > db-dump.sql

Download the Latest setup.sh Script

Make sure you have the latest version of the setup.sh script:

curl -fsSL -o setup.sh https://raw.githubusercontent.com/makeplane/plane/master/deploy/selfhost/install.sh

Execute the script:

./setup.sh

This will bring up a menu, choose Option 5 to Upgrade.

Select a Action you want to perform:

1) Install (x86_64)
2) Start
3) Stop
4) Restart
5) Upgrade
6) View Logs
7) Backup Data
8) Exit

Action [2]: 5

This choice stops all the containers, downloads the latest docker-compose.yaml and new variables-upgrade.env files. The plane.env file won’t be overwritten, after the update completes choose Option 6 to exit the menu.

After the upgrade, open variables-upgrade.env and compare it with your existing plane.env file. Copy new variables from variables-upgrade.env to plane.env and set correct values. This is essential to make sure that all the changes are configured for the latest version.

Once the plane.env file is updated, execute the setup.sh script again and choose Option 2 to start the services.

Verify the Upgrade

Access the Plane dashboard and confirm that the version matches the latest release.

Please note that, even though all services are running it takes 1-2 minutes until you can access the dashboard.

Using a Specific Version of Plane

If the latest version is unsuitable for your setup or dependencies, you can specify a desired version during upgrade.

How to Use a Specific Version

Change the variable APP_RELEASE in the plane.env file and instead of stable add the desired tag e.g. v0.20-dev.

APP_RELEASE=v0.20-dev

Execute the setup.sh script and choose Option 4 to restart the services.

Test the Deployment

After the upgrade, verify that the specified version is installed by checking the Plane dashboard or run docker ps command to check if the services are running the specific desired version:

docker ps

By explicitly setting the version, you keep control over what features or changes are introduced to your instance.

Setting Up a Custom Artifact Registry for Plane Images

A custom artifact registry enables better control over Docker images, ensuring you deploy only trusted and tested versions of Plane.

Pull and Retag Plane Images

Fetch the desired Plane image and push it to your custom registry:

docker pull makeplane/plane:stable
docker tag makeplane/plane:stable customregistry/plane:customTag
docker push customregistry/plane:customTag

Make sure you do this for all Docker images Plane uses.

Update Plane’s Configuration

Edit your Plane deployment configuration to point to the custom registry.

Create a variable in the plane.env file called DOCKER_IMAGE with the value of the custom registry and use that variable in the docker-compose.yaml for all the needed services.

Authenticate (If Required)

For private registries, log in before pulling images:

docker login customeregistry.com

Benefits of Using a Custom Artifact Registry

• Enhanced Security: Ensures only vetted and secure images are used, reducing exposure to malicious or compromised images.
• Version Control: Stores only specific versions, preventing accidental upgrades or downgrades.

Downsides to Using a Custom Artifact Registry

• Increased Maintenance: You’ll need to regularly update, secure, and monitor the registry itself.
• Complexity: Setting up and managing a custom registry adds overhead compared to relying on public repositories.

Conclusion

Upgrading and customizing a self-hosted Plane instance can be straightforward with tools like the setup.sh script and custom artifact registries.

By upgrading to the latest version or targeting a specific release, you guarantee stability and compatibility within your environment. Adding a custom registry introduces control and security, though it comes with extra setup and maintenance requirements.

These approaches offer a robust and secure foundation for managing your Plane instance. They allow your team to focus on what matters most — collaboration and productivity.