Connection Setup

Caydem runs on Supabase as its database platform. You choose where your Supabase instance runs; Caydem connects to it the same way regardless. This page covers each deployment option and how to connect Caydem to it.

The connection screen — “Connect to Your Books” — appears on first launch and whenever you need to add or switch a connection. Your connection string is stored locally and never sent to Pivoten.

Deployment Options

Local Development (Supabase CLI)

The Supabase CLI runs a full Supabase stack on your machine using Docker. This is the recommended approach for a Single System deployment or for development and testing.

The Supabase CLI requires Docker. There is no local Supabase install without it.

# Install the CLI, then start Supabase
supabase init
supabase start

Once running, Caydem automatically scans the default local address:

Address	What it is
postgresql://postgres:postgres@localhost:54322/postgres	Supabase CLI local instance

If Caydem finds a running instance it shows a green checkmark — give the connection a name and click Connect & open. If nothing is found, confirm Docker is running and supabase start completed successfully, then scan again.

Self-Hosted via Docker Compose

The official and recommended way to self-host Supabase is Docker Compose. This is the right choice for a Server or Appliance deployment — a dedicated machine, VM, or on-site server that your team connects to.

Follow Supabase’s Docker self-hosting guide to stand up the stack on your server, then connect Caydem with the server’s address:

Field	Description	Example
Connection String	Supabase PostgreSQL URL	postgresql://postgres:password@10.0.1.20:5432/postgres
Display Name	Label in the workspace switcher	Office Server

Click Test connection to verify, then Connect & open when it passes.

When self-hosting, you are responsible for server provisioning, security updates, backups, high availability, and monitoring. See Supabase self-hosting responsibilities.

For SSL-enabled servers, append ?sslmode=require to your connection string.

Self-Hosted via Kubernetes

For organizations running Kubernetes, the supabase-kubernetes community project provides Helm charts to deploy Supabase on a k8s cluster.

Once deployed, connect Caydem the same way as a Docker Compose deployment — paste in the PostgreSQL connection string from your cluster, test it, and connect.

Kubernetes self-hosting is community-supported, not officially maintained by Supabase.

Supabase Cloud

Connect to a hosted Supabase.com project. This is the fully managed option — Supabase handles infrastructure, backups, and updates. This is the backing database for Caydem’s Cloud tier.

Create a project on Supabase.com, then find your connection string under Settings → Database → Connection string (use the URI / direct connection format).

Field	Description	Example
Connection String	Direct connection URI from the Supabase dashboard	postgresql://postgres:password@db.abc123.supabase.co:5432/postgres
Display Name	Label in the workspace switcher	Production

Always append ?sslmode=require for cloud connections.

Test the connection and click Connect & open when it passes.

After Connecting

Once a connection succeeds, Caydem:

1. Applies any pending database migrations automatically — no manual SQL required.
2. Saves the connection profile locally. Subsequent launches reconnect without showing the connection screen.
3. Checks whether a company exists. If not, the setup wizard launches to create one.

Switching Connections

To add a new connection or switch databases, use the workspace switcher in the top-left of the app. You can maintain multiple saved connections — for example, a local development instance and a production cloud project.

Troubleshooting

“Could not reach the database server.” The host is unreachable. For local instances, confirm Docker is running and supabase start completed. For remote instances, check the hostname, port, and firewall rules.

“Database login failed.” The username or password is wrong. The default Supabase local credentials are postgres / postgres. For self-hosted and cloud instances, check your .env or Supabase dashboard for the correct credentials.

“Secure connection (SSL) failed.” Append ?sslmode=require to your connection string.

Connection test passes but Caydem shows migration errors. The connecting role may lack permission to create tables. Ensure the role has sufficient privileges to run schema migrations.

Next Steps

With a working connection, continue to Company Setup to create your first company, configure its fiscal year, and choose a chart of accounts.