Skip to main content

Deploy your operator

The operator is a server handling all the transaction building and publishing easily via an easy-to-use, documented API. The deployment process of the operator is done via the following steps:

  1. Publish an application on-chain via Carmentis Desk.
  2. Deploy an instance of the operator using Docker Compose.
  3. Attach the operator to your Carmentis Desk.
  4. Configure the operator.

Deploy the operator​

Deploy the operator for development​

The deployment of the operator in development is done using Docker. Note that when running the operator without dealing with a reverse proxy, the execution of the operator can be done using the following simple docker command:

docker run \
  --rm\
  -d\
  -p 3000:3000\
  -v ./operator:/app/operator\
  ghcr.io/carmentis/operator

Deploy the operator for production​

This above command is particularly useful for local development. In a production environment, we recommend deploying the operator using Docker Compose and Caddy. In order to make the deployment easier, we recommand the usage of the CLI.

Prerequisites​

To set up your operator, you need to ensure the following requirements:

  • Be sure to have docker installed on your system. If not, follow the official Docker installation guide.
  • Be sure to have a server with a public IP address.
  • You also need to have one DNS entry pointing on the IP address of your server. For the sake of example, we assume the following DNS entry operator.your-domain-name pointing to your server.

Step 1: Install npm and the CLI​

The first step is to install the node package manager (npm).

sudo apt update && sudo apt upgrade -y && sudo apt install npm && sudo npm i -g @cmts-dev/carmentis-cli

Step 2: Generate the config​

To generate the configuration of your operator, execute the following command and answer to the response interactively (replace the $PATH_TO_GENERATE_CONFIG with the path where the configuration is generated):

cmts operator init-config --home $PATH_TO_GENERATE_CONFIG

Step 3: Run the operator​

To run the operator, execute the following command (replace the $PATH_TO_GENERATE_CONFIG with the path where the configuration has been generated):

cd $PATH_TO_GENERATE_CONFIG && docker compose up -d

Configure the operator​

Once your operator server is running, you can configure it using Carmentis Desk. Before starting the configuration, ensure you have installed Carmentis Desk and have a published application (you will need your application's vbId). Finally, ensure you have wallet on your desk (hopefully, if you have created and published an application, you have already a wallet in your desk so no further action is required).

To configure your operator, follow the steps below:

  1. Create a new operator instance on your desk. You have to indicate a name (just for you) and an endpoint to talk with the operator.
  2. Once created, the desk will show a setup form. In the dropdown, select the wallet you want to use to create the first admin account of the operator.
  3. Once setup, the desk will show a login page, select the same wallet as the one you used to create the operator. Later one, other wallets will be able to login on the operator by adding new users. But for now, only this wallet can be used.
  4. Once logged in, you can create a new wallet on the operator or import a wallet from your desk to the operator. It is up to you to choose which one you want to use.
  5. Once a wallet is created or imported on the operator, you can declare an application related to your wallet. Note that the application you declare must be the one you published on-chain. The operator will not work otherwise and does not check for publication status yet.
  6. Once the application is declared, create an API key. This API key can be used by your (real) applications to interact with the operator.
Operator APIs

The operator exposes two APIs:

  • /admin/api: the one used by [Carmentis Desk] to administrate the operator (protected by JWT tokens).
  • /api/v1/transactions: the one used by your applications to interact with the operator (protected by API keys).

Troubleshooting​

Operator requests end in 404

In development, if the request ends in 404, ensure that the operator listens at the right port by checking the logs. Indeed, when starting the operator, if the specified port is not available, the operator attempts to listen on another free port.

The workspace shows an operator connection error

When the workspace cannot establish a connection with the operator, it displays an error message. The problem might come from several issues:

  • The operator server is not running.
  • The operator server does not listen to the correct port. It might come from an invalid port specification in the configuration, from a port conflict (the operator tries another free port), or an invalid docker port mapping.
  • The Caddyfile is invalid if you have provided twice the same URL for the two servers or an invalid URL.
  • The DNS configuration is not updated. You might have to update the DNS configuration to point to the correct IP address.
Docker not permitted (permission denired while trying to connect to the docker API at unix:///var/run/docker.sock)

In a fresh install of Docker, you might be unable to execute the docker run --rm hello-world command. To solve this issue, we highly recommend you to follow the official Docker documentation for post-installations. For more convinience, you can run the following commands but remember to check the Official Docker documentation:

sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker
docker run --rm hello-world
The docker-compose command is not found

Have you tried docker compose?