The installer and the agent

This page is for your customer's database administrator as much as for you: link to it from your cabinet.

The install command runs the LokaDB installer in the customer's network. It asks for their PostgreSQL database, prepares it, and then stays running as the agent: the tunnel through which your service reaches that database. It opens no port: every connection goes out, to the LokaDB API (HTTPS), to the service provider's relay, and to the customer's own Postgres.

What the customer needs

• A server with Docker in their network that reaches their PostgreSQL.
• An administrator login of that database: a superuser, or a role with CREATEROLE that may grant CREATE on the database (its owner). The password is used once and never stored.
• Outbound connections to the LokaDB API and to the relay address in the command.

The command

From the service provider's cabinet (or the customer's cabinet link). It works once, for 30 minutes.

docker run -it --name lokadb-agent-org7 --restart unless-stopped \
  -v lokadb-agent-org7:/state --network host \
  <installer image> --api <API address> --token lsi_…

Run interactively (-it), it asks:

Question
Host, Port [5432]	Where the database listens, as seen from this server.
Database	An empty one, or one of the customer's: the service adds its tables in a schema lokadb.
Administrator role [postgres]
Password	Not shown, not stored.

Without a terminal (docker run -d, or automation), it takes the same from the environment (the service provider gets this form of the command too):

Variable	Flag
LOKADB_PG_HOST	--pg-host	required
LOKADB_PG_PORT	--pg-port	default 5432
LOKADB_PG_DATABASE	--pg-database	required
LOKADB_PG_USER	--pg-user	default postgres
LOKADB_PG_PASSWORD or LOKADB_PG_PASSWORD_FILE		required
LOKADB_PG_SSLMODE	--pg-sslmode	default prefer
LOKADB_API, LOKADB_TOKEN	--api, --token	in the command
LOKADB_STATE	--state	default /state
LOKADB_AGENT_STATUS=off		no status reports
LOKADB_DEBUG		any value: a detailed log

What it does

1. Takes the token and shows which move and organization it is for, and the service provider's runner key (fingerprint): the same as in their panel. Compare them if in doubt.
2. Connects to the database as the administrator.
3. Creates two roles, lokadb_app_org7 and lokadb_dml_org7, with new random passwords and no special rights (no superuser, no role or database creation, no replication, no row-level-security bypass), and lets them connect (the first may also create in the database).
4. Creates the extensions the service's tables need, and says for each: there, created, or missing.
5. Checks that both roles can log in, and seals their passwords to the runner's key: only the service provider's runner can open them.
6. Starts the agent and tells the service it is ready. From here the service provider's runner checks the database and moves the organization; the cabinet shows the progress.

Done ends the setup; the container keeps running as the agent (detach with Ctrl-P Ctrl-Q). It reports its state every minute (LOKADB_AGENT_STATUS=off turns this off).

The volume

/state (the lokadb-agent-org7 volume) holds the agent's certificate and key, its secret and the setup's result. A restart of the container or the server goes straight back to the agent, with no token and no questions. Keep the volume: without it the agent must be installed again with a new command.

Missing extensions

If the database lacks an extension the tables need and the installer could not create it (the package is not on the server), nothing moves until it is there. Install the package on the Postgres server, then:

docker exec -it lokadb-agent-org7 lokadb-agent-installer extensions

It asks for the administrator login again, creates what is missing and says what is still missing. The service provider's panel lists the extensions missing per organization too.

Updating the agent

Once the agent is connected, the cabinet shows its update command (the API: agent_update_command in the move). It pulls the new image and starts the agent again on the same volume, without a token:

docker pull <installer image> && docker rm -f lokadb-agent-org7 && \
docker run -d --name lokadb-agent-org7 --restart unless-stopped \
  -v lokadb-agent-org7:/state --network host <installer image>

Troubleshooting

It says	What to do
this install token is not valid: it was used, replaced or cancelled	Get a new command from the cabinet.
this install token has expired	Get a new command from the cabinet (each works for 30 minutes).
the move is …: nothing to install now	The move was cancelled or is over; ask the service provider.
your service provider's runner is not connected / is offline	It waits up to 5 minutes; the service provider has to start their runner.
the service at … is not reachable	Allow outbound HTTPS to the LokaDB API from this server.
not a terminal, and LOKADB_PG_… not set	Run with docker run -it, or set the variables.
connecting to …	Check the host, port, login and password, and that this server reaches the database.
role … cannot create roles	Use a superuser or a role with CREATEROLE.
role … cannot grant CREATE on database …	Use the database's owner or a superuser.
role lokadb_app_org… cannot log in at … from this container	Allow both roles in pg_hba.conf from this server's address (scram-sha-256), reload Postgres, run the command again.
Some extensions are missing in your database	See Missing extensions.
this agent's secret is not valid any more	The organization left the service (moved back or cancelled); the container can be removed.

When the organization is moved back or the move is cancelled, the service provider's runner revokes the agent.