Getting started with Self Hosted Canonic

You can self-host Canonic on your own infrastructure. It's available as a simple docker image that you can get up and running in just a few minutes. It runs completely independently from our hosted offering.

When to self-host?

You can either use Canonic as a cloud offering by building and deploying your projects on Canonic's infrastructure, or self-host. But why go through all the effort of deploying a service on your own infrastructure?

Data privacy and security

Self-hosting enables customers to fully control their data, ensuring that sensitive data stays inside their own private, safe environment. For companies handling sensitive consumer data or organizations with stringent data protection regulations, this is especially crucial.

Flexibility and customization

Users that self-host Canonic applications have the freedom to design their hosting environment to suit their needs. To optimize the performance of their application, they can link with existing systems, set up security controls, and fine-tune performance parameters.

Controlled updates

Canonic's self-hosted version doesn't communicate with Canonic apart from a simple license check call. All updates must be manually accepted, keeping all the control with you. Your applications will run as-is independent of Canonic Cloud's uptime.

Getting Started

Let's dive into self-hosting Canonic. You can follow the steps in this tutorial in your local environment. But to host it, you would need a t3.medium (aws) equivalent instance.

Prerequisites

2vCPU / 4GB Memory
Docker

Obtain a license key

Signup on the cloud version of Canonic at https://app.canonic.dev
Navigate to the profile page. Then click on Access Tokens.
Create an access token with all the permission boxes ticked.
Store this key somewhere as you will need it on the next step.

Configuring Environment Variables

To make things incredibly simple to host, we've packed all of Canonic into a single docker image. A few environment variables must be configured before running the service.

Let's create a folder and .env file within it.

mkdir canonic-self-hosted
cd canonic-self-hosted
touch .env

Now, let's store our license key and other parameters which are essential to run the application properly. We use the license key to validate your subscription plan. Self-hosted Canonic's features and limits are based on the plan you've selected.

# .env
LICENSE="<YOUR LICENSE KEY>"
APP_URL="<THE IP OR HOSTNAME WHERE YOU ARE HOSTING CANONIC>"
GENERATOR_URL="<THE IP OR HOSTNAME WHERE YOU ARE HOSTING CANONIC>/app"
MONGO_URL="<MONGODB CONNECTION STRING>"

These parameters need to be added in the .env file for each service that you want to access. For example, if you want to have Google Authentication, make sure to add your OAuth Client ID, Secret key and Callback URL. For more details on the various environment variables that can be added, check out Configuration.

Running the Docker Image

Now let's run the docker image. We pass in the env file we just created along with some volumes to persist data. Canonic runs on port 80 inside the docker container. We're mapping it to 3000 but you can map it to whatever port you would like the app to be accessible on.

docker run -it \
  --platform=linux/amd64 \
  -p 3000:80 \
  --env-file .env \
  trycanonic/canonic

Once you run the command, it takes a few seconds for the application to boot up. Once it's ready you can visit http://localhost:3000. You'll be presented with the signup screen.

If you're hosting this on the cloud, then replace localhost with the hostname or ip of your instance.

Things to note

It is essential to set up SSL for your self-hosted copy if you want to host it on the cloud, as the platform requires a secure origin like localhost or https.

If you want to use the docker image directly, it is necessary to provision the SSL certificate and run NGINX natively.

However, in order to make things simple, we have created a Docker Compose file with all the necessary configuration to set up https for your self hosted version. You can read more about it here.

At this point, in behavior, your self-hosted copy should behave exactly like the cloud version of the platform. Feel free to signup and get started! The number of collaborators and users would be limited by the pricing plan you pick.