DEV Community: Vultr

Deploying Typebot - Open-Source Conversational Form Builder

Sanskriti Harmukh — Wed, 23 Sep 2026 19:27:14 +0000

Typebot is an open-source, visually-driven conversational form and chatbot builder. It serves as a self-hosted alternative to hosted form and chatbot builders, giving you full data ownership and control over integrations and embedding. This guide deploys Typebot on a Linux server using Docker Compose with PostgreSQL, Redis, and Traefik for reverse proxy and TLS termination. By the end, you'll have a working Typebot instance with a published bot embedded on a sample page.

Prerequisites

Before you begin, you need to:

Have access to a Linux-based server as a non-root user with sudo privileges.
Install Docker and Docker Compose.
Configure two domain A records pointing to your server, such as builder.example.com and viewer.example.com.
Have an email address for Let's Encrypt certificate registration.

Set Up the Directory Structure and Environment Variables

To prevent data loss during container restarts or updates, the deployment relies on host-mounted volumes for PostgreSQL, Redis, and TLS certificates. Docker Compose reads secrets, URLs, and credentials from a .env file in the project directory and substitutes them into the service definitions at startup.

1. Create a project directory for the Typebot deployment:

$ mkdir -p ~/typebot/{pgdata,redisdata,letsencrypt,data}

The command creates four subdirectories:

pgdata: Persists PostgreSQL database files.
redisdata: Stores Redis data used by Typebot's Redis-backed features, such as sign-in rate limiting and media uploads.
letsencrypt: Stores Traefik ACME certificates for automatic HTTPS renewal.
data: Stores Mailpit local email data.

2. Navigate to the project directory:

$ cd ~/typebot

3. Generate a strong random encryption secret that is used to encrypt sensitive data such as credentials and bot content:

$ openssl rand -base64 24

Copy the output. Use this value for the ENCRYPTION_SECRET variable in the next steps when creating the .env file.

Store this value securely and never change it once the deployment starts handling real data. Typebot uses ENCRYPTION_SECRET to encrypt stored credentials, and rotating it makes any previously encrypted data unreadable.

4. Create a .env file to store the environment variables:

$ nano .env

5. Add the following variables:

DOMAIN_BUILDER=builder.example.com
DOMAIN_VIEWER=viewer.example.com
LETSENCRYPT_EMAIL=admin@example.com

ENCRYPTION_SECRET=YOUR_GENERATED_SECRET

POSTGRES_DB=typebot
POSTGRES_USER=typebot
POSTGRES_PASSWORD=STRONG_DATABASE_PASSWORD
DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}

REDIS_URL=redis://redis:6379

NEXTAUTH_URL=https://${DOMAIN_BUILDER}
NEXT_PUBLIC_VIEWER_URL=https://${DOMAIN_VIEWER}

ADMIN_EMAIL=admin@example.com
DEFAULT_WORKSPACE_PLAN=UNLIMITED
DISABLE_SIGNUP=false

SMTP_HOST=mailpit
SMTP_PORT=1025
SMTP_SECURE=false
NEXT_PUBLIC_SMTP_FROM="Typebot Notifications <notifications@example.com>"
SMTP_IGNORE_TLS=true
SMTP_USERNAME=YOUR_SMTP_USERNAME
SMTP_PASSWORD=YOUR_SMTP_PASSWORD


TYPEBOT_DEBUG=false
AUTH_TRUST_HOST=true

DEFAULT_WORKSPACE_PLAN=UNLIMITED applies the unlimited plan to every new workspace, not only the administrator's. Signup stays open until later in this guide, so anyone who registers during that window also receives an unlimited workspace.

Replace the following:

builder.example.com and viewer.example.com with your actual domains pointing to the server.
admin@example.com with your email for Let's Encrypt and admin access.
YOUR_GENERATED_SECRET with the output from the openssl command.
STRONG_DATABASE_PASSWORD with a secure password for PostgreSQL.
YOUR_SMTP_USERNAME with your username.
YOUR_SMTP_PASSWORD with a strong, secure password for your mail.
notifications@example.com in NEXT_PUBLIC_SMTP_FROM with a sender address on your own domain.

Save and close the file.

Deploy with Docker Compose

Docker Compose orchestrates the full Typebot stack: Traefik for reverse proxy and HTTPS, PostgreSQL for persistent storage, Redis for sessions and caching, the Builder and Viewer services, and Mailpit for email. This configuration is adapted from the official Typebot Docker setup to use Traefik and persistent volumes.

1. Create the Docker Compose manifest:

$ nano docker-compose.yaml

2. Add the following content:

services:
  traefik:
    image: traefik:v3.7.8
    container_name: traefik
    restart: unless-stopped
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "./letsencrypt:/letsencrypt"
      - "/var/run/docker.sock:/var/run/docker.sock:ro"

  postgres:
    image: postgres:16-alpine
    container_name: typebot-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - "./pgdata:/var/lib/postgresql/data"
    healthcheck:
      test: ["CMD", "pg_isready", "-d", "${POSTGRES_DB}", "-U", "${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:8-alpine
    container_name: typebot-redis
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - "./redisdata:/data"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

  typebot-builder:
    image: baptistearno/typebot-builder:3.17.2
    container_name: typebot-builder
    restart: unless-stopped
    env_file:
      - .env
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.typebot-builder.rule=Host(`${DOMAIN_BUILDER}`)"
      - "traefik.http.routers.typebot-builder.entrypoints=websecure"
      - "traefik.http.routers.typebot-builder.tls.certresolver=letsencrypt"
      - "traefik.http.services.typebot-builder.loadbalancer.server.port=3000"

  typebot-viewer:
    image: baptistearno/typebot-viewer:3.17.2
    container_name: typebot-viewer
    restart: unless-stopped
    env_file:
      - .env
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.typebot-viewer.rule=Host(`${DOMAIN_VIEWER}`)"
      - "traefik.http.routers.typebot-viewer.entrypoints=websecure"
      - "traefik.http.routers.typebot-viewer.tls.certresolver=letsencrypt"
      - "traefik.http.services.typebot-viewer.loadbalancer.server.port=3000"

  mailpit:
    image: axllent/mailpit:v1.30.5
    container_name: mailpit
    restart: unless-stopped
    ports:
      - "127.0.0.1:8025:8025"
      - "127.0.0.1:1025:1025"
    environment:
      MP_MAX_MESSAGES: 5000
      MP_DATABASE: /data/mailpit.db
      MP_SMTP_AUTH_ACCEPT_ANY: 1
      MP_SMTP_AUTH_ALLOW_INSECURE: 1
    volumes:
      - ./data:/data

traefik
- Acts as a reverse proxy and HTTPS termination layer for both the Builder and Viewer.
- Listens on ports 80 and 443 for incoming web traffic and automatically redirects HTTP to HTTPS.
- Requests and renews TLS certificates from Let's Encrypt using the email address defined in LETSENCRYPT_EMAIL.
- Stores certificates persistently in the ./letsencrypt directory.
postgres
- Runs PostgreSQL 16 as the primary database to store all bots, user responses, workspaces, and configuration data.
- Uses database credentials defined in the .env file.
- Persists database files in the ./pgdata directory on the host.
- Includes a health check to ensure the database is fully initialized before the Typebot services start.
redis
- Runs Redis 8 (Alpine), a required dependency for the Builder and Viewer services to start.
- Supports sign-in rate limiting by IP and multiple media uploads on WhatsApp.
- Persists data in the ./redisdata directory.
- Includes a health check to verify Redis is responsive.
typebot-builder
- Runs the official Typebot Builder application (the visual editor).
- Loads all configuration and secrets from the .env file.
- Connects to both PostgreSQL and Redis, waiting for their health checks to pass before starting.
- Registers itself with Traefik using Docker labels so it can be securely accessed via your builder domain.
typebot-viewer
- Runs the official Typebot Viewer application (the public-facing bot runtime).
- Loads all configuration and secrets from the .env file.
- Connects to both PostgreSQL and Redis, waiting for their health checks to pass before starting.
- Registers itself with Traefik using Docker labels so published bots can be accessed and embedded via your viewer domain.
mailpit
- Runs Mailpit as a local email testing tool, bound to 127.0.0.1 so it is not exposed publicly.
- Exposes the web UI on port 8025 and the SMTP service on port 1025 locally.
- Stores email data in the ./data directory.
- Lets Typebot send sign-in verification codes to a local inbox instead of a real mailbox.
- Lets you read messages in your local browser at http://localhost:8025 via an SSH tunnel after deployment.
Mailpit only captures mail locally. It never delivers to a real inbox, so it is not a production email path. To send real email, either request that your provider unblock outbound port 25 on this instance and self-host a mail delivery service such as Postal, pointing SMTP_HOST, SMTP_PORT, SMTP_USERNAME, and SMTP_PASSWORD at it, or route outbound mail through an authenticated relay on port 587 or 465. Many cloud providers block outbound port 25 by default on new instances, so check with your provider before choosing a self-hosted mail path.

Save and close the file.

3. Validate the syntax of the file:

$ docker compose config

4. Start the services in detached mode:

$ docker compose up -d

5. Verify that the containers are running and healthy:

$ docker compose ps

All six containers should show a status of Up, with mailpit, typebot-postgres, and typebot-redis also showing (healthy).

6. View the logs for the Builder service to ensure it connected successfully to the database and Redis:

$ docker compose logs typebot-builder

7. View the logs for the Viewer service to ensure it connected successfully to the database and Redis:

$ docker compose logs typebot-viewer

Access and Configure Typebot

Typebot requires email-based verification instead of a password for the first sign-in, which this deployment routes through Mailpit. This section confirms the administrator account, verifies that both the Builder and Viewer domains are reachable, and closes public registration.

Open your web browser and navigate to the Builder domain using HTTPS.

   https://builder.example.com

Replace builder.example.com with the actual domain you set in the .env file for the Builder.

Sign in with the email address defined in the ADMIN_EMAIL variable. A six-digit verification code is sent to your Mailpit email server.

Because Mailpit is bound to 127.0.0.1 and not exposed publicly, access its web interface by setting up an SSH local port forwarding tunnel from your local terminal.

   $ ssh -N -L 8025:localhost:8025 USERNAME@YOUR_SERVER_IP

Replace USERNAME with your server's username and YOUR_SERVER_IP with your server's IP. If your server uses key-based SSH authentication, add -i /path/to/your-private-key before -N. The -N flag tells SSH to only forward the port instead of opening a remote shell.

Open your local web browser and navigate to the Mailpit inbox at http://localhost:8025.
Open the Mailpit inbox and copy the verification code sent by Typebot.

Return to the Builder tab and enter the code to complete sign-in.
Return to the terminal running the SSH tunnel and press Ctrl+C to close it, since Mailpit access is no longer needed until the next sign-in.
Open the Viewer domain in a new tab.

   https://viewer.example.com

Replace viewer.example.com with the domain you configured in the .env file.

Click the dashboard link on the Viewer page to verify that it opens the Builder interface.

Open your .env file to disable public registrations now that your admin account is created.
```
$ nano .env
```
Update the signup configuration.
```
DISABLE_SIGNUP=true
```
Save and close the file, then apply the changes to the Builder container.
```
$ docker compose up -d --force-recreate typebot-builder
```
This prevents unauthorized users from registering new accounts on your public Builder instance.

Create and Embed a Typebot

Typebot publishes each bot as a hosted page on the Viewer domain and provides a JavaScript snippet that embeds that page into any website. Publishing a bot makes it reachable at that public link before you add it to a page.

In the Builder tab still open from the previous section, click Create a typebot.
Select Start from scratch to create a new bot manually.

From the top left corner, change the typebot name to your preferred title, for example, My first bot.
In the visual editor, drag a Text bubble block onto the canvas and enter a welcome message, for example, "Hello! How can I help you today?"
Drag a connection line from the Start block's output dot to the Text bubble block so the flow begins there.
Drag an Input block, for example Text, and connect it to the previous block.

Click Publish in the top-right corner.
Under Embed your typebot, click Iframe.
Copy the <iframe> snippet shown in the dialog.
Open the main HTML file of your sample website or any page where you want to add the bot.

Paste the snippet just before the closing </body> tag.

<iframe
    title="Typebot"
    src="https://viewer.example.com/your-bot-id"
    style="border: none; width: 100%; height: 600px"
></iframe>

Replace viewer.example.com/your-bot-id with the link shown in the Iframe dialog.

Save the file and open your website in a browser to test the bot.
Return to the Typebot Builder, open the Results tab, and verify that responses are being captured.

Test a Bot

Typebot's built-in templates route respondents through a Choice input block, so each button ends its own path through the flow instead of all leading to the same message. The Results tab records which option a respondent picked as its own column, alongside any text or email fields the flow collects.

Click Create a typebot.
Select Start from template.
Choose the Customer Support template from the left pane, then click Use this template.
Click Publish.
Open the link shown under Your typebot links.
Click one of the response options, for example I have a feature request. Verify that the bot responds with a follow-up message and a link, then click Restart to return to the beginning.
Return to the Typebot Builder, open the Results tab, and verify that the option you clicked appears under the Menu column.

Next Steps

Connect a real SMTP provider so sign-in codes and notifications reach real inboxes
Explore Typebot's integrations, such as Google Sheets, webhooks, and Zapier
Build a multi-step lead qualification or support triage flow using Choice and Condition blocks
Set up scheduled backups of the PostgreSQL volume before handling production traffic

For the full guide with additional tips, visit the original article on Vultr Docs.

Deploying BookStack - Open-Source Documentation Platform

Sanskriti Harmukh — Wed, 23 Sep 2026 19:26:11 +0000

BookStack is an open-source documentation platform for creating, organizing, and managing knowledge bases. It provides a web interface for structuring documentation into Shelves, Books, Chapters, and Pages, making it easy to organize technical documentation, internal wikis, project documentation, and team knowledge. This guide deploys BookStack on a Linux server using Docker Compose with MariaDB for data storage and Traefik as the reverse proxy for TLS termination, then walks through creating Shelves, Books, Chapters, and Pages through the web interface. By the end, you'll have a working BookStack instance with a sample documentation hierarchy served securely over HTTPS.

Prerequisites

Before you begin, you need to:

Have access to a Linux-based server (with at least 4 CPU cores and 8 GB of RAM) as a non-root user with sudo privileges.
Install Docker and Docker Compose.
Create a DNS A record pointing to your server's IP address (for example, book.example.com).

Set Up the Directory Structure, Configuration, and Environment Variables

BookStack requires a configuration file to define environment variables, database connections, and application settings. The setup includes persistent storage for the MariaDB database, uploaded files, and application configuration to ensure data is retained across server restarts.

1. Create the project directory:

$ mkdir ~/bookstack

2. Navigate to the project directory:

$ cd ~/bookstack

3. Generate a secret key for the BookStack application:

$ echo "base64:$(openssl rand -base64 32)"

Save the output for use in the environment file.

4. Create an environment file:

$ nano .env

5. Add the following configuration:

DOMAIN=book.example.com
LETSENCRYPT_EMAIL=admin@example.com

# BookStack Settings
APP_URL=https://book.example.com
APP_KEY=YOUR_GENERATED_APP_KEY

# Database Settings
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=STRONG_DATABASE_PASSWORD_1
DB_ROOT_PASSWORD=STRONG_DATABASE_PASSWORD_2

# Time Zone
TZ=UTC

Replace:

book.example.com with your domain name.
admin@example.com with your email address.
YOUR_GENERATED_APP_KEY with the output from the earlier step.
STRONG_DATABASE_PASSWORD_1 and STRONG_DATABASE_PASSWORD_2 with two different secure passwords.

Save and close the file.

Deploy with Docker Compose

The deployment stack uses Traefik as the reverse proxy for TLS termination and deploys BookStack and MariaDB containers with mounted application and database volumes. This configuration is based on the official BookStack Docker Compose configuration.

1. Create the Docker Compose manifest file:

$ nano docker-compose.yaml

2. Add the following configuration:

services:
  traefik:
    image: traefik:v3.7.11
    container_name: traefik
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entryPoint.to=websecure"
      - "--entrypoints.web.http.redirections.entryPoint.scheme=https"
      - "--certificatesresolvers.myresolver.acme.tlschallenge=true"
      - "--certificatesresolvers.myresolver.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.myresolver.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt
    restart: unless-stopped

  mariadb:
    image: lscr.io/linuxserver/mariadb:11.8.8
    container_name: bookstack_mariadb
    env_file:
      - .env
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=${TZ}
      - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD}
      - MYSQL_DATABASE=${DB_DATABASE}
      - MYSQL_USER=${DB_USERNAME}
      - MYSQL_PASSWORD=${DB_PASSWORD}
    volumes:
      - ./bookstack_data/mariadb_data:/config
    restart: unless-stopped

  bookstack:
    image: lscr.io/linuxserver/bookstack:version-v26.05.4
    container_name: bookstack
    depends_on:
      - mariadb
    env_file:
      - .env
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=${TZ}
      - APP_URL=${APP_URL}
      - APP_KEY=${APP_KEY}
      - DB_HOST=mariadb
      - DB_PORT=3306
      - DB_DATABASE=${DB_DATABASE}
      - DB_USERNAME=${DB_USERNAME}
      - DB_PASSWORD=${DB_PASSWORD}
    volumes:
      - ./bookstack_data/app_data:/config
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.bookstack.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.bookstack.entrypoints=websecure"
      - "traefik.http.routers.bookstack.tls.certresolver=myresolver"
      - "traefik.http.services.bookstack.loadbalancer.server.port=80"
    restart: unless-stopped

Save and close the file.

In the above manifest:

traefik: Serves as the reverse proxy and TLS termination point, using the official Traefik image. It exposes ports 80 and 443 for HTTP and HTTPS traffic, stores certificates in the ./letsencrypt directory, and automatically provisions them through Let's Encrypt.
mariadb: Stores the BookStack database, including users, Shelves, Books, Chapters, Pages, and application data, using the LinuxServer.io MariaDB image. The database name, username, password, and root password come from the .env file, and the data persists in the ./bookstack_data/mariadb_data directory.
bookstack: Runs the BookStack web application, using the LinuxServer.io BookStack image, and starts only after the mariadb service is available. The application URL, application key, database connection settings, and time zone come from the .env file, the application configuration and uploaded files persist in the ./bookstack_data/app_data directory, and the Traefik labels route HTTPS requests for your domain to this container.

All three services use restart: unless-stopped, so they restart automatically if they fail or the server reboots.

3. Start all services in detached mode:

$ docker compose up -d

4. Verify that the services are running:

$ docker compose ps

The output displays all the containers in the Up state.

5. View the service logs to confirm all components started successfully:

$ docker compose logs

Access and Configure BookStack

BookStack provides a web interface for organizing and managing documentation using shelves, books, and pages. The dashboard provides a central place to manage your documentation and workspace.

Open your web browser and navigate to BookStack at https://book.example.com, replacing book.example.com with your configured domain.

On the screen, enter Email as admin@admin.com and Password as password to create the admin account.
Click Log In to access the BookStack dashboard.

To change the login password, click the Admin menu in the top-right navigation and select My Account. Then, under the My Account menu on the left, select Access & Security. From here, you can change your password and configure Multi-Factor Authentication (MFA).

Build and Organize Your Documentation in BookStack

BookStack organizes documentation into a hierarchy that makes related content easy to manage and navigate. This workflow creates a Shelf, builds a Book and Chapter within it, and adds a Page containing sample documentation to validate the setup and demonstrate the platform's core features.

Create a Shelf

A Shelf serves as the top-level container for organizing related Books within a documentation collection.

Click Shelves in the top navigation menu.
Click Create one now or New Shelf under the Actions panel.
Enter a shelf name, such as Team Documentation, and an optional description.
Click Save Shelf.

Create a Book within the Shelf

A Book groups related Chapters and Pages together within a Shelf.

Open the Team Documentation shelf you created in the previous step.
Click Create New Book.
Enter a book name, such as Employee Onboarding, and an optional description.
Click Save Book.

Create a Chapter within the Book

Chapters organize related Pages into logical sections within a Book.

Open the Employee Onboarding book you created in the previous step.
Click Add a chapter.
Enter a chapter name, such as Getting Started, and an optional description.
Click Save Chapter.

Create and Edit a Page within the Chapter

Pages are where you create, edit, and organize documentation using the built-in rich text editor.

Open the Getting Started chapter you created in the previous step.
Click Create a new page.
Enter a page title such as Development Environment Setup.
Add a brief introduction, followed by a heading titled Prerequisites.
Add a bulleted list describing the required software and tools.
Click Save Page.

Reopen the Development Environment Setup page, click Edit under the Actions panel, and add another heading named Next Steps, then click Save Page again.

Next Steps

Invite additional users and configure role-based permissions for each Shelf or Book
Enable a search index and explore BookStack's built-in page revision history
Configure an external authentication provider such as LDAP or SAML for team sign-in
Set up scheduled backups of the MariaDB database and the uploaded file storage

For the full guide with additional tips, visit the original article on Vultr Docs.

Deploying Uptime Kuma - Self-Hosted Status Page and Monitoring Tool

Sanskriti Harmukh — Wed, 23 Sep 2026 19:24:27 +0000

Uptime Kuma is a self-hosted monitoring tool that tracks the availability of websites, APIs, TCP ports, DNS records, and other services. It provides a clean dashboard to display uptime metrics and trigger alerts through 90+ notification services, including email, Slack, and Telegram, when a service goes down or recovers. This guide deploys Uptime Kuma on a Linux server using Docker Compose behind a Traefik reverse proxy. By the end, you'll have a working Uptime Kuma instance with an active monitor, a notification channel, and a public status page.

Prerequisites

Before you begin, you need to:

Have access to a Linux-based server as a non-root user with sudo privileges.
Install Docker and Docker Compose.
Configure a domain A record, such as kuma.example.com, pointing to your server's public IP address.
Add your user to the docker group to run Docker commands without sudo, then start a new shell session to apply the change.

Set Up the Directory Structure and Environment Variables

The project directory holds the Docker Compose file, the persistent data directory, and the environment variables shared between the Traefik and Uptime Kuma containers.

1. Create the project directory:

$ mkdir ~/uptime-kuma

2. Enter the project directory:

$ cd ~/uptime-kuma

3. Create the persistent data directory for Uptime Kuma:

$ mkdir -p data

4. Create the environment variable file:

$ nano .env

5. Add the following variables to the file:

DOMAIN=kuma.example.com
LETSENCRYPT_EMAIL=admin@example.com

Replace the following placeholders:

kuma.example.com: Your registered domain name pointing to the server's IP address.
admin@example.com: Your email address for Let's Encrypt certificate notifications.

Save and close the file.

Deploy with Docker Compose

Traefik and Uptime Kuma run as separate containers on a shared Docker network. Traefik terminates TLS on the configured domain and forwards requests to Uptime Kuma's internal port, keeping Uptime Kuma off the public internet entirely.

1. Create the Docker Compose file:

$ nano docker-compose.yaml

2. Add the following configuration:

services:
  traefik:
    image: traefik:v3.7.11
    container_name: traefik
    restart: unless-stopped
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--certificatesresolvers.le.acme.httpchallenge=true"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt
    networks:
      - kuma-net

  uptime-kuma:
    image: louislam/uptime-kuma:2.5.3
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    networks:
      - kuma-net
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.kuma.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.kuma.entrypoints=websecure"
      - "traefik.http.routers.kuma.tls=true"
      - "traefik.http.routers.kuma.tls.certresolver=le"
      - "traefik.http.services.kuma.loadbalancer.server.port=3001"

networks:
  kuma-net:
    driver: bridge

Save and close the file.

In the above configuration:

traefik: The reverse proxy that listens on ports 80 and 443, redirects all HTTP traffic to HTTPS, and automatically provisions TLS certificates from Let's Encrypt using the HTTP challenge method.
uptime-kuma: The monitoring service that stores data in the ./data directory. The Traefik labels configure domain routing, enable HTTPS, and forward traffic to the Uptime Kuma application on port 3001.
kuma-net: A shared bridge network that allows Traefik and Uptime Kuma to communicate internally without exposing internal ports to the host.

3. Start all services in detached mode:

$ docker compose up -d

4. Verify that all containers are running:

$ docker compose ps

The output displays two running containers: Traefik and Uptime Kuma.

Configure Uptime Kuma

Uptime Kuma does not report any status information until you create an administrator account and configure at least one monitor.

Open a web browser and navigate to the domain configured in the .env file.

   https://kuma.example.com

On the database setup page, select SQLite, then click Next. SQLite requires no extra configuration and works with the single-container deployment in this guide. The MariaDB/MySQL option connects to a separate database server that this deployment does not provision.
The account creation page appears. Enter a username, enter a strong password in both the Password and Repeat Password fields, then click Create.
After you create the account, the Uptime Kuma dashboard opens. Click + Add New Monitor.

Configure the monitor settings:

Monitor Type: Select the type of service to monitor. Choose HTTP(s) for websites and APIs, TCP Port for port-based services, or DNS for domain records.
Friendly Name: Enter a descriptive name for the monitor (for example, My Website).
URL: Enter the full URL of the service to monitor (for example, https://example.com).
Heartbeat Interval: Set the polling frequency in seconds. The default is 60.

Click Save to activate the monitor. The dashboard adds the monitor with an Unknown status. The status updates to Up or Down after the first heartbeat check runs within 60 seconds.

Configure Alert Notifications

Uptime Kuma does not send alerts by default. You must configure a notification channel and assign it to individual monitors before it triggers on a status change.

Click the profile avatar in the top-right corner and select Settings.
Navigate to the Notifications tab and click Set Up Notification.
Select a notification type from the dropdown. Supported channels include email (SMTP), Slack, Telegram, Discord, and PagerDuty, among others.
Enter the required credentials or webhook URL of the selected notification channel.
Click Test to send a test notification and verify the configuration is working.
Click Save to confirm the notification setup.
Open the settings for each monitor that should use this notification channel, select the notification from the Notifications list, and click Save.

Create a Status Page

A status page groups one or more monitors into a public view, separate from the administrator dashboard, so you can share it with users or team members without granting them access to the full Uptime Kuma interface.

Click Status Pages in the top navigation bar.
Click New Status Page.
Enter a Name for the status page (for example, Service Status), then enter a Slug using only lowercase letters, numbers, and hyphens (for example, status creates the URL https://kuma.example.com/status/status). Click Next.
The status page editor opens. The Title field is pre-filled with the name entered in the previous step. Add a Description if needed, then configure the remaining display settings as needed.
Click Add Group to create a section, then use the Add a monitor dropdown to select a monitor and add it to the group.
Click Save to publish the status page.
Open the status page URL in a browser to verify it loads and displays the monitor statuses.

   https://kuma.example.com/status/status

Replace the path with the slug configured in step 3.

Next Steps

Add more monitors for your other websites, APIs, and internal services
Configure additional notification channels so different teams get alerted through their preferred tool
Build separate status pages for internal and public audiences
Explore Uptime Kuma's tag and group features to organize monitors at scale

For the full guide with additional tips, visit the original article on Vultr Docs.

Deploying Kubeflow as an Azure ML Alternative

Sanskriti Harmukh — Wed, 23 Sep 2026 19:23:38 +0000

Azure Machine Learning is Microsoft's cloud-native machine learning platform that provides experiment tracking, managed compute, pipelines, a model registry, and model serving as hosted services within the Azure ecosystem, but it ties teams to Azure-specific APIs, managed compute pricing, and Microsoft's tooling. Kubeflow is an open-source machine learning platform built on Kubernetes that provides self-hosted alternatives to Azure ML capabilities through modular, portable components, letting organizations retain complete control over infrastructure, data residency, scalability, and operational costs. This guide deploys Kubeflow on a Kubernetes cluster as a self-managed replacement for Azure Machine Learning, covering installation with Kustomize manifests, notebook setup, ML pipeline orchestration, distributed training with the Trainer v2 API, model serving through KServe, hyperparameter optimization using Katib, RBAC and access management, object storage integration, and migration considerations for existing Azure ML workflows. By the end, you'll have a self-hosted ML platform running notebooks, pipelines, distributed training, model serving, and automated hyperparameter tuning.

Understanding Azure Machine Learning vs Kubeflow

Azure ML and Kubeflow provide comparable ML platform capabilities, but they differ in deployment and operational models. Azure ML delivers these as fully managed services within the Azure ecosystem, while Kubeflow provides equivalent open-source components that run on any Kubernetes cluster. The following table maps each Azure ML feature to its Kubeflow counterpart.

Azure Machine Learning	Kubeflow Equivalent	Description
Azure ML Notebooks	Kubeflow Notebooks	Interactive development environments with JupyterLab, VS Code, and RStudio
Azure ML Jobs	Kubeflow Trainer	Distributed training for PyTorch, DeepSpeed, MLX, JAX, and XGBoost workloads
Azure ML Pipelines	Kubeflow Pipelines (KFP)	Directed Acyclic Graph (DAG) based ML workflow orchestration
Azure ML Model Registry	Kubeflow Model Registry	Versioned model artifact management with metadata tracking
Azure ML Endpoints	KServe	Serverless model serving with autoscaling and canary deployments
Azure ML Experiments	Katib	Automated hyperparameter tuning with multiple search algorithms

Self-hosting with Kubeflow eliminates per-minute compute charges, keeps all data within your own cluster, runs on any cloud provider or on-premises hardware, and allows complete customization of every component.

Prerequisites

Before you begin, you need to:

Have access to a multi-node Kubernetes cluster that runs Kubernetes 1.31 or later with at least 4 CPU cores and 16 GB of RAM per node (minimum 3 nodes recommended).
Install kubectl and configure it to connect to your cluster.
Install Kustomize version 5.4.3 or later.
Have a default StorageClass that is configured in your cluster for provisioning persistent volumes.

Install Kubeflow

Kubeflow uses Kustomize to deploy its components as Kubernetes resources. The official kubeflow/manifests repository contains all component manifests that are organized under common/ for shared infrastructure services such as Istio, cert-manager, and Dex, and under applications/ for Kubeflow-specific applications such as Pipelines, Notebooks, and KServe.

Deploy Kubeflow via Manifests

The following steps clone the Kubeflow manifests repository and deploy all components to the cluster.

1. Verify the Kubernetes cluster connection:

$ kubectl cluster-info

2. Check the Kubernetes server version:

$ kubectl version

Verify that the Server Version field shows version 1.31 or later.

3. Clone the official Kubeflow manifests repository:

$ git clone https://github.com/kubeflow/manifests.git

4. Switch to the manifests directory:

$ cd manifests

5. Check out the latest stable release tag:

$ git checkout 26.03

6. Deploy all Kubeflow components:

The command uses a bounded retry loop that attempts the installation up to 5 times, which accommodates the time that Kubernetes CRDs and webhooks need to register before dependent resources apply. The loop exits automatically after a successful apply or after reaching the retry limit.

$ for i in 1 2 3 4 5; do kustomize build example | kubectl apply --server-side --force-conflicts -f - && break || { echo "Attempt $i failed, retrying in 30s..."; sleep 30; }; done

The first one or two attempts may output errors about CRDs or webhooks not being established. These errors are expected and resolve on subsequent attempts after the CRDs register. The loop exits automatically when the apply succeeds, which typically happens on the second or third attempt. The full installation takes approximately 10 to 15 minutes after the final successful apply for all pods to reach a Running state. The --server-side --force-conflicts flags are required because some Kubeflow CRDs exceed the annotation size limit that standard kubectl apply supports.

The default installation uses the email user@example.com and password 12341234. Change these credentials before exposing Kubeflow to any network. See the Set Up Access Control section later in this article for instructions.

Verify Installation

After the deployment completes, verify that all Kubeflow components are running and the CRDs are registered.

1. Check that all pods in the kubeflow namespace reach a Running state:

$ kubectl get pods -n kubeflow --field-selector=status.phase!=Succeeded

Verify that all listed pods display a Running status with all containers ready. If any pods show CrashLoopBackOff or Pending, check their logs with kubectl logs -n kubeflow POD-NAME and verify that the cluster meets the minimum resource requirements.

2. Check that the Istio ingress gateway service is running:

$ kubectl get svc istio-ingressgateway -n istio-system

Verify that the service appears in the output.

3. Check that Kubeflow and its component CRDs are registered:

$ kubectl get crd | grep -E "kubeflow|kserve|katib|istio|knative|trainer" | wc -l

The output displays the count of registered CRDs across Kubeflow and its components. A count of 40 or more indicates a complete installation.

Create Default User Profile

Kubeflow uses profiles to provide namespace-level isolation for each user. The default installation does not automatically provision a user namespace, so you need to create one manually.

1. Create a new file called user-profile.yaml:

$ nano user-profile.yaml

2. Add the following configuration:

apiVersion: kubeflow.org/v1
kind: Profile
metadata:
  name: kubeflow-user-example-com
spec:
  owner:
    kind: User
    name: user@example.com

Save and close the file.

3. Apply the profile manifest:

$ kubectl apply -f user-profile.yaml

This command creates an isolated namespace called kubeflow-user-example-com with default Role-Based Access Control (RBAC) policies and a service account for the default user.

4. Verify that the namespace exists:

$ kubectl get namespace kubeflow-user-example-com

5. Verify that the default service account exists:

The service account takes a few seconds to provision after the profile is created. Wait 10 seconds before running this command.

$ kubectl get serviceaccount default-editor -n kubeflow-user-example-com

Configure Storage

Kubeflow components such as Notebooks, Pipelines, and the Model Registry require persistent storage. The cluster needs a default StorageClass to dynamically provision Persistent Volume Claims (PVCs).

1. Verify that a default StorageClass exists:

$ kubectl get storageclass

The default StorageClass shows (default) next to its name. If no default exists, set one by annotating an existing StorageClass. Replace STORAGE-CLASS-NAME with the name of an existing StorageClass from the output above.

$ kubectl patch storageclass STORAGE-CLASS-NAME -p '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "true"}}}'

Configure Kubeflow Notebooks

Kubeflow Notebooks provides managed JupyterLab, VS Code, and RStudio environments that run as Kubernetes pods with direct access to cluster resources, GPUs, and persistent storage. This component serves as a self-hosted alternative to Azure Machine Learning notebooks and compute instances.

Access Dashboard

Set up port forwarding and log in to the Kubeflow Central Dashboard.

1. Set up port forwarding to access the Kubeflow Central Dashboard:

$ kubectl port-forward svc/istio-ingressgateway -n istio-system 8080:80

Open http://localhost:8080 in a web browser. The Kubeflow login screen appears. Click Sign in with Dex.

Enter the default credentials on the Dex login form and click Login.

Email: user@example.com
Password: 12341234

The Kubeflow Central Dashboard loads with links to Notebooks, Pipelines, Katib Experiments, KServe Endpoints, and other components. Select kubeflow-user-example-com from the namespace dropdown at the top.

Create Notebook Server

Launch a new notebook server from the Kubeflow dashboard.

Navigate to Notebooks in the left sidebar and click New Notebook.
Enter ml-workspace in the Name field.
Select the notebook environment from the image cards. Choose JupyterLab for a general-purpose data science environment. Select VisualStudio Code for a code editor interface, or RStudio for R-based statistical computing. To use a specific image version, select Custom Notebook from the dropdown below the cards.
Set Minimum CPU to 0.5 and Minimum Memory Gi to 1.
Leave the Workspace Volume at the default 5Gi. This volume persists data across notebook restarts.
Click Launch and wait for the notebook pod to reach a Running state. The status indicator turns green when the notebook is ready.

Connect to Notebook

Open the JupyterLab interface and verify that ML libraries are accessible.

Click Connect next to the notebook server name. A new tab opens with the JupyterLab interface.
Click Python 3 (ipykernel) under the Notebook section in the launcher to create a new notebook. Paste the following code into a cell and press Shift+Enter to run it.

   import numpy as np
   from sklearn.ensemble import RandomForestClassifier
   from sklearn.model_selection import train_test_split

   X = np.random.randn(1000, 10)
   y = (X[:, 0] + X[:, 1] > 0).astype(int)
   X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

   model = RandomForestClassifier(n_estimators=100)
   model.fit(X_train, y_train)
   print(f"Accuracy: {model.score(X_test, y_test):.4f}")

The cell outputs an accuracy score such as Accuracy: 0.9750.

Set Up Kubeflow Pipelines

Kubeflow Pipelines is a workflow orchestration platform for building, automating, and managing machine learning pipelines as Directed Acyclic Graphs (DAGs). Each step in a pipeline executes within its own containerized environment, improving reproducibility, portability, and experiment versioning across ML workflows. It acts as an open-source, self-hosted alternative to Azure Machine Learning pipelines and workflow orchestration features.

Deploy Sample Pipeline

Install the KFP SDK, define a three-step pipeline, compile it, and submit a run through the internal API. The following steps use both the notebook terminal and the cluster management terminal where specified.

Inside JupyterLab, click File > New > Terminal to open a terminal tab.

2. Create the pipeline definition file:

$ nano sample_pipeline.py

3. Add the following configuration:

from kfp import dsl, compiler

@dsl.component(base_image="python:3.11-slim")
def preprocess() -> str:
    import json
    data = {"samples": 1000, "features": 10, "status": "preprocessed"}
    return json.dumps(data)

@dsl.component(base_image="python:3.11-slim")
def train(input_data: str) -> str:
    import json
    data = json.loads(input_data)
    result = {"model": "random_forest", "accuracy": 0.95, "input": data}
    return json.dumps(result)

@dsl.component(base_image="python:3.11-slim")
def evaluate(input_data: str):
    import json
    result = json.loads(input_data)
    print(f"Model: {result['model']}, Accuracy: {result['accuracy']}")

@dsl.pipeline(name="sample-ml-pipeline")
def ml_pipeline():
    preprocess_task = preprocess()
    train_task = train(input_data=preprocess_task.output)
    evaluate(input_data=train_task.output)

compiler.Compiler().compile(ml_pipeline, "pipeline.yaml")
print("Pipeline compiled successfully")

Save and close the file.

4. Compile the pipeline to generate the YAML definition:

$ python3 sample_pipeline.py

5. Switch to the cluster management terminal and create the authorization policy manifest:

This policy allows the notebook namespace to call the Kubeflow Pipelines API through the Istio service mesh.

$ nano allow-pipeline-access.yaml

6. Add the following configuration:

apiVersion: security.istio.io/v1beta1
kind: AuthorizationPolicy
metadata:
  name: allow-notebook-to-pipeline
  namespace: kubeflow
spec:
  selector:
    matchLabels:
      app: ml-pipeline
  rules:
  - from:
    - source:
        namespaces: ["kubeflow-user-example-com"]

Save and close the file.

7. Apply the authorization policy:

$ kubectl apply -f allow-pipeline-access.yaml

8. Switch to the notebook terminal and upload the compiled pipeline to Kubeflow Pipelines through the internal API:

$ curl -s -F "uploadfile=@pipeline.yaml" -H "kubeflow-userid: user@example.com" http://ml-pipeline.kubeflow.svc.cluster.local:8888/apis/v2beta1/pipelines/upload

The command returns a JSON response that contains the pipeline_id. Note this value for the next step.

9. Create an experiment to organize pipeline runs:

$ curl -s -X POST -H "Content-Type: application/json" -H "kubeflow-userid: user@example.com" http://ml-pipeline.kubeflow.svc.cluster.local:8888/apis/v2beta1/experiments -d '{"display_name":"default","namespace":"kubeflow-user-example-com"}'

The command returns a JSON response that contains the experiment_id. Note this value for the next step.

10. Start a pipeline run:

Replace PIPELINE-ID and EXPERIMENT-ID with the values from the previous steps.

$ curl -s -X POST -H "Content-Type: application/json" -H "kubeflow-userid: user@example.com" http://ml-pipeline.kubeflow.svc.cluster.local:8888/apis/v2beta1/runs -d '{"display_name":"test-run","experiment_id":"EXPERIMENT-ID","pipeline_version_reference":{"pipeline_id":"PIPELINE-ID"},"runtime_config":{}}'

Monitor Execution

The pipeline run status is visible from the command line and from the Kubeflow dashboard. The dashboard provides a graph view that shows each step's completion state.

1. Verify that the workflow completed:

$ kubectl get workflows -n kubeflow-user-example-com

Verify that the STATUS column shows Succeeded.

Navigate to Pipelines in the left sidebar of the Kubeflow dashboard, then click Experiments. Click default, then click the test-run entry. The graph view shows the preprocess, train, and evaluate steps each marked with a green checkmark when the run completes successfully.

Configure Distributed Training

Kubeflow Trainer v2 provides a unified TrainJob API for running distributed training jobs across frameworks including PyTorch, DeepSpeed, MLX, JAX, and XGBoost. The Trainer uses ClusterTrainingRuntime resources that define pre-configured runtime environments, which separates infrastructure configuration from training logic. Kubeflow Trainer replaces Azure ML Jobs with native Kubernetes-based distributed training.

Create Training Job

Create and deploy a distributed PyTorch training job that uses the torch-distributed runtime. Run the following commands from the cluster management terminal.

1. Create the TrainJob manifest:

$ nano trainjob.yaml

2. Add the following configuration:

apiVersion: trainer.kubeflow.org/v1alpha1
kind: TrainJob
metadata:
  name: pytorch-training
  namespace: kubeflow-user-example-com
spec:
  runtimeRef:
    name: torch-distributed
  trainer:
    image: ghcr.io/kubeflow/katib/pytorch-mnist-cpu:v0.19.0
    numNodes: 2
    resourcesPerNode:
      requests:
        cpu: "500m"
        memory: "1Gi"
      limits:
        cpu: "1"
        memory: "2Gi"

Save and close the file. The runtimeRef field references the torch-distributed ClusterTrainingRuntime, which configures the PyTorch distributed training environment. The numNodes field specifies the number of training nodes that Kubeflow provisions for the job.

3. Apply the training manifest:

$ kubectl apply -f trainjob.yaml

Monitor Training

Check the training job status from the cluster management terminal.

1. Verify the TrainJob status:

$ kubectl get trainjob -n kubeflow-user-example-com

The STATE column shows Complete when training finishes successfully.

Deploy Model Serving with KServe

KServe provides a Kubernetes CRD called InferenceService for deploying, scaling, and managing ML model endpoints. It supports serverless inference with autoscaling from zero, canary rollouts, and multi-model serving across frameworks including TensorFlow, PyTorch, scikit-learn, XGBoost, and ONNX. KServe also supports deploying models directly from Hugging Face Hub using the hf:// URI schema and from the Kubeflow Model Registry using the model-registry:// protocol. KServe is included in the Kubeflow installation and replaces Azure ML Endpoints.

Create InferenceService

Deploy a pre-trained scikit-learn model and expose it as a serving endpoint. Run the following commands from the cluster management terminal.

1. Create the model serving manifest:

$ nano sklearn-iris.yaml

2. Add the following configuration:

apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
  name: sklearn-iris
  namespace: kubeflow-user-example-com
  annotations:
    sidecar.istio.io/inject: "false"
spec:
  predictor:
    model:
      modelFormat:
        name: sklearn
      storageUri: "gs://kfserving-examples/models/sklearn/1.0/model"
      resources:
        requests:
          cpu: 100m
          memory: 256Mi
        limits:
          cpu: "1"
          memory: 1Gi

Save and close the file.

3. Apply the InferenceService manifest:

$ kubectl apply -f sklearn-iris.yaml

4. Wait for the InferenceService to become ready:

$ kubectl get inferenceservice sklearn-iris -n kubeflow-user-example-com -w

The READY column changes to True when the model is loaded and serving. Press Ctrl+C to stop watching. Navigate to KServe Endpoints in the Kubeflow dashboard sidebar to view the deployed model.

Test Model Endpoint

Send a test inference request to verify that the model is serving predictions.

1. Run the following command from the Kubeflow notebook terminal, which has direct access to the cluster-internal service endpoint:

$ curl -s --max-time 30 -H "Content-Type: application/json" http://sklearn-iris-predictor-00001-private.kubeflow-user-example-com.svc.cluster.local/v1/models/sklearn-iris:predict -d '{"instances": [[6.8, 2.8, 4.8, 1.4], [6.0, 3.4, 4.5, 1.6]]}'

The response returns predicted class labels.

{"predictions": [1, 1]}

Configure Hyperparameter Tuning

Katib is the Kubeflow component that provides automated hyperparameter tuning and neural architecture search. It supports multiple search algorithms including random search, grid search, Bayesian optimization, Tree-structured Parzen Estimator (TPE), and CMA Evolution Strategy. Katib replaces Azure ML Experiments and Automatic Model Tuning with a Kubernetes-native solution.

Create Tuning Experiment

Katib experiments are defined and submitted through the Katib Python SDK from a JupyterLab notebook cell. The SDK creates the experiment resource on the cluster and manages trial pod configuration and metrics collection automatically.

1. Open a terminal in JupyterLab by clicking File > New > Terminal and install the Katib Python SDK:

$ pip install kubeflow-katib

Close the terminal tab and create a new Python notebook by clicking File > New > Notebook, then selecting Python 3 (ipykernel) as the kernel. Run the following code in a cell to define an objective function and launch a tuning experiment.

   import kubeflow.katib as katib

   def objective(parameters):
       import time
       time.sleep(5)
       result = 4 * int(parameters["a"]) - float(parameters["b"]) ** 2
       print(f"result={result}")

   parameters = {
       "a": katib.search.int(min=10, max=20),
       "b": katib.search.double(min=0.1, max=0.2)
   }

   katib_client = katib.KatibClient(namespace="kubeflow-user-example-com")
   name = "tune-experiment"
   katib_client.tune(
       name=name,
       objective=objective,
       parameters=parameters,
       objective_metric_name="result",
       objective_type="maximize",
       algorithm_name="random",
       max_trial_count=4,
       parallel_trial_count=2,
       resources_per_trial={"cpu": "1", "memory": "1Gi"},
   )

The tune() method creates a Katib experiment that runs 4 trials (2 in parallel) using random search. The cell output includes a Katib Experiment tune-experiment link here line. Click here to open the experiment directly in the Katib Experiments tab and monitor trial progress. The experiment status turns green when all trials complete.

Retrieve the optimal hyperparameters by running the following code in the next cell.

   katib_client.wait_for_experiment_condition(name=name)
   print(katib_client.get_optimal_hyperparameters(name))

Set Up Access Control

Kubeflow uses Dex as its OpenID Connect (OIDC) identity provider and Istio for network-level authorization. Each user gets an isolated namespace, which is called a profile, with its own resources, secrets, and RBAC policies.

Configure Authentication

The Dex ConfigMap uses hashFromEnv: DEX_USER_PASSWORD to read the password hash from an environment variable rather than storing it directly in the ConfigMap. To change the default password, update the Secret that provides this environment variable to the Dex pod.

1. Install the bcrypt Python package to generate a password hash:

$ pip install bcrypt

2. Generate a bcrypt hash for the new password. Replace YOUR-SECURE-PASSWORD with the password you want to set:

$ python3 -c "import bcrypt; print(bcrypt.hashpw(b'YOUR-SECURE-PASSWORD', bcrypt.gensalt()).decode())"

Copy the output hash for use in the next step.

3. Update the dex-passwords Secret with the new hash. Replace GENERATED-BCRYPT-HASH with the hash output from the previous step:

$ kubectl create secret generic dex-passwords -n auth \
    --from-literal=DEX_USER_PASSWORD='GENERATED-BCRYPT-HASH' \
    --dry-run=client -o yaml | kubectl apply -f -

The command outputs a warning about a missing annotation. This is expected because dex-passwords was created by Kubeflow without --save-config. Verify that the output ends with secret/dex-passwords configured.

4. Restart the Dex deployment to apply the changes:

$ kubectl rollout restart deployment dex -n auth

To add additional static users or configure external identity providers such as Lightweight Directory Access Protocol (LDAP), GitHub, or Google, add entries to the staticPasswords list or connector entries in the Dex ConfigMap. See the Dex documentation for details.

Implement RBAC

Each additional user needs a profile that follows the same manifest structure as the default user profile. Replace the metadata.name and owner.name fields with the new user's details, then apply the manifest with kubectl apply -f.

To give an existing user access to another user's namespace without creating a separate profile, navigate to the target namespace in the Kubeflow dashboard namespace dropdown. Click Manage Contributors in the left sidebar and enter the user's email address.

Integrate Object Storage

ML workflows generate large artifacts including trained models, pipeline outputs, datasets, and logs. Kubeflow uses SeaweedFS as its default S3-compatible object storage backend for artifact persistence. KServe also supports S3-compatible storage for loading model artifacts.

Configure Storage Backend

The default Kubeflow installation deploys SeaweedFS in the kubeflow namespace with pre-configured credentials. Verify that the storage deployment is running.

1. Check the SeaweedFS pod status:

$ kubectl get pods -n kubeflow -l app=seaweedfs

2. For production deployments, replace SeaweedFS with an external S3-compatible object storage service:

Replace YOUR-ACCESS-KEY and YOUR-SECRET-KEY with the access key and secret key for your storage service, then update the mlpipeline-minio-artifact secret with the new credentials.

$ kubectl create secret generic mlpipeline-minio-artifact -n kubeflow --from-literal=accesskey=YOUR-ACCESS-KEY --from-literal=secretkey=YOUR-SECRET-KEY --dry-run=client -o yaml | kubectl apply -f -

Test Storage Integration

Configure KServe to access SeaweedFS for loading model artifacts stored in the cluster.

1. Create a storage secret for KServe model storage:

$ nano s3-storage-secret.yaml

2. Add the following configuration. Replace ACCESS-KEY and SECRET-ACCESS-KEY with any strong keyword:

apiVersion: v1
kind: Secret
metadata:
  name: s3-storage-secret
  namespace: kubeflow-user-example-com
  annotations:
    serving.kserve.io/s3-endpoint: "seaweedfs.kubeflow:8333"
    serving.kserve.io/s3-usehttps: "0"
type: Opaque
stringData:
  AWS_ACCESS_KEY_ID: "ACCESS-KEY"
  AWS_SECRET_ACCESS_KEY: "SECRET-ACCESS-KEY"

Save and close the file.

3. Apply the storage secret:

$ kubectl apply -f s3-storage-secret.yaml

Migration from Azure Machine Learning

Migrating from Azure ML to Kubeflow involves exporting existing assets and mapping each Azure ML component to its Kubeflow equivalent. Notebooks transfer without format changes since both platforms use the standard Jupyter notebook format. Training scripts, pipelines, and experiments require rewriting to replace Azure ML SDK calls with Kubeflow and KFP SDK equivalents.

Export Notebooks: Download Azure ML Studio notebooks as .ipynb files from the console or by using the Azure CLI. Upload them directly to Kubeflow Notebook servers, since both platforms use standard Jupyter notebook format. Update any azure.ai.ml SDK calls that rely on Azure ML-specific APIs.
Convert Training Scripts: Azure ML training scripts that use azure.ai.ml SDK job and command patterns such as command(...), MLClient(...), ScriptRunConfig(...), or framework-specific job configurations need to be converted into standard framework training scripts for Kubernetes-based execution. Replace Azure ML-specific environment variables, datastore mounts, and output paths such as AZUREML_MODEL_DIR, ./outputs, and Azure ML input/output bindings with Kubernetes volume mount paths. Package the training code into container images and reference them in TrainJob manifests.
Migrate Pipelines: Azure ML Pipelines are defined using the azure.ai.ml SDK and need rewriting with the KFP SDK. Azure ML Pipelines use Python-based DAG definitions via the azure.ai.ml SDK; replace it with KFP's @dsl.pipeline decorated functions.
Export Models: Download trained model artifacts from Azure Machine Learning model registries, datastores, or blob storage using the Azure CLI or azure.ai.ml SDK. Upload them to the object storage backend connected to Kubeflow and update the storageUri field in KServe InferenceService manifests to reference the new storage location. KServe supports the same model formats commonly used in Azure ML deployments, including TensorFlow SavedModel, TorchScript, ONNX, and scikit-learn pickle models, without requiring additional conversion.
Migrate Experiments: Export Azure ML experiment tracking data using the MLflow SDK's mlflow.artifacts.download_artifacts() API call. For hyperparameter tuning, recreate tuning jobs as Katib experiments with equivalent search spaces and objective metrics using the Katib Python SDK.

Next Steps

Configure GPU scheduling for notebooks and training jobs that need accelerated compute
Set up multi-tenancy with additional user profiles and namespace-level resource quotas
Harden the deployment for production, including TLS termination, network policies, and backup of the object storage backend
Explore additional Katib search algorithms and KServe canary rollout strategies for safer model updates

For the full guide with additional tips, visit the original article on Vultr Docs.

Deploying Logto as a GCP Identity Platform Alternative

Sanskriti Harmukh — Wed, 23 Sep 2026 19:22:47 +0000

Google Cloud Identity Platform is Google's managed CIAM service for web and mobile applications, providing user account management, customizable authentication flows, social and enterprise identity federation, MFA, and integration with Google Cloud services. It removes the need to operate an identity store, but it bills per monthly active user (MAU) in tiers where email, phone, anonymous, and social sign-in are free to 50,000 MAU while OIDC and SAML federation are free only to 50 MAU before per-user charges begin, meters phone and multi-factor messages separately, and ties the user store and its flows to a Google Cloud project. Logto is an open-source Customer Identity and Access Management (CIAM) platform built on OAuth 2.1 and OpenID Connect (OIDC) that covers the same ground on self-hosted infrastructure without per-user billing or cloud provider API dependencies — a branded sign-in experience, social and enterprise SSO federation, MFA, role-based access control (RBAC), organizations for multi-tenancy, and webhooks, all stored in a PostgreSQL database you control. This guide walks through deploying Logto as an alternative to Google Cloud Identity Platform: the Docker Compose deployment with Traefik and automatic HTTPS, the admin console, sign-in experience and branding, email and social login connectors, enterprise SSO, MFA, RBAC and API resources, organizations, application registration, webhooks, deployment verification, and migration from Identity Platform. By the end, you'll have a fully configured, self-hosted CIAM platform and a documented path for moving an existing Identity Platform user base onto it.

Before you begin, you need a Linux-based server with at least 2 CPU cores and 8 GB of RAM as a non-root user with sudo privileges, Docker and Docker Compose installed, and DNS A records pointing to your server's IP address for two subdomains: auth.example.com (Logto Core API and sign-in experience) and admin.example.com (Admin Console).

Understanding Logto Architecture

Logto covers most Identity Platform components through a self-hosted, OIDC-standard platform. The following table maps each Identity Platform feature to its Logto counterpart and notes where no equivalent exists.

Identity Platform	Logto	Description
Identity Platform Users	Logto Users	User management and hosted login pages.
Identity Platform SAML/OIDC Federation	Logto Enterprise SSO Connectors (SAML/OIDC)	Federation with external identity providers.
Identity Platform FirebaseUI	Logto Sign-in Experience	Fully customizable branded authentication flow.
Identity Platform Social Providers	Logto Social Connectors	Integration with over 30 social identity providers.
Identity Platform MFA	Logto MFA	TOTP, WebAuthn/Passkeys, SMS, Email OTP, and backup codes.
Identity Platform Blocking Functions	Logto Webhooks	Asynchronous event-driven webhooks (not inline).
Identity Platform OAuth Clients / SDK Configs	Logto Applications	OIDC clients for SPAs, web apps, and M2M services.
Identity Platform Tenants (multi-tenancy)	Logto Organizations	Role-based access control and multi-tenant management.
Identity Platform Account Defender	No direct equivalent	Use WAF, rate limiting, or a reverse proxy for protection.
Firebase / GCP Admin SDKs	Logto SDKs	Official SDKs for over 30 modern development frameworks.

The Logto Core service (auth.example.com) exposes the OIDC endpoints, Management API (/api), and the user-facing sign-in experience. The Admin Console (admin.example.com) is a separate frontend that manages tenant configuration through the Management API.

1. Deploy Logto with Docker Compose

Logto requires PostgreSQL 14 or later to store users, configuration, and session data. This section deploys Logto for production using Docker Compose, Traefik for automatic HTTPS with Let's Encrypt, and PostgreSQL for durable storage.

1. Create the project directory structure:

$ mkdir -p ~/logto/traefik/letsencrypt

2. Navigate to the project directory:

$ cd ~/logto

3. Create the Logto environment file:

$ nano .env

4. Add the following configuration:

# Domain Configuration
LOGTO_CORE_DOMAIN=auth.example.com
LOGTO_ADMIN_DOMAIN=admin.example.com

# Logto Endpoints
ENDPOINT=https://auth.example.com
ADMIN_ENDPOINT=https://admin.example.com

# SSL Configuration
LETSENCRYPT_EMAIL=admin@example.com

# Database
DB_PASSWORD=DB-PASSWORD

# Logto image version
TAG=1.40.1

# Pins the Docker Engine API version to avoid socket communication errors with newer Traefik releases
DOCKER_API_VERSION=1.54

Replace auth.example.com and admin.example.com with your subdomains, admin@example.com with your Let's Encrypt notification address, DB-PASSWORD with a strong PostgreSQL password, and 1.40.1 with the Logto release you want to deploy (check the Logto releases page for the latest stable version).

5. Download the Logto Docker Compose file for the pinned release. Pin the compose file URL to the same release tag as TAG in the environment file — this file is maintained by Logto.

$ wget https://raw.githubusercontent.com/logto-io/logto/v1.40.1/docker-compose.yml

6. Update the docker-compose.yml file for production use. The official compose file ships with hardcoded database credentials labeled for demonstration; replace those defaults before deployment.

$ nano docker-compose.yml

Find the app service and update the DB_URL under environment:

- DB_URL=postgres://postgres:${DB_PASSWORD}@postgres:5432/logto

Find the postgres service and update POSTGRES_PASSWORD:

POSTGRES_PASSWORD: ${DB_PASSWORD}

Pin the PostgreSQL image to a specific release for reproducible deployments:

image: postgres:17.5-alpine

7. Create the Traefik Docker Compose override file:

$ nano traefik/docker-compose.yml

8. Add the following configuration:

services:
  traefik:
    image: traefik:v3.7.0
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.myresolver.acme.httpchallenge=true"
      - "--certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.myresolver.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.myresolver.acme.storage=/letsencrypt/acme.json"
      - "--entrypoints.web.http.redirections.entryPoint.to=websecure"
      - "--entrypoints.web.http.redirections.entryPoint.scheme=https"
    ports:
      - "80:80"
      - "443:443"
    environment:
      - DOCKER_API_VERSION=${DOCKER_API_VERSION}
      - TRUST_PROXY_HEADER=true
    volumes:
      - ./letsencrypt:/letsencrypt
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      default:
        aliases:
          - ${LOGTO_CORE_DOMAIN}
          - ${LOGTO_ADMIN_DOMAIN}
  app:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.logto-core.rule=Host(`${LOGTO_CORE_DOMAIN}`)"
      - "traefik.http.routers.logto-core.entrypoints=websecure"
      - "traefik.http.routers.logto-core.tls.certresolver=myresolver"
      - "traefik.http.routers.logto-core.service=logto-core"
      - "traefik.http.services.logto-core.loadbalancer.server.port=3001"
      - "traefik.http.routers.logto-admin.rule=Host(`${LOGTO_ADMIN_DOMAIN}`)"
      - "traefik.http.routers.logto-admin.entrypoints=websecure"
      - "traefik.http.routers.logto-admin.tls.certresolver=myresolver"
      - "traefik.http.routers.logto-admin.service=logto-admin"
      - "traefik.http.services.logto-admin.loadbalancer.server.port=3002"

Traefik routes HTTPS traffic to Logto on subdomain-based host rules — port 3001 serves the Core API and sign-in experience, port 3002 serves the Admin Console. Let's Encrypt certificates are provisioned automatically once DNS resolves to this server. This stack pins svhd/logto to the TAG value in .env, traefik to v3.7.0, and PostgreSQL to 17.5-alpine.

9. Start the Logto stack:

$ docker compose -f docker-compose.yml -f traefik/docker-compose.yml up -d

10. Verify the containers are running:

$ docker ps

The output displays running containers for Traefik, Logto, and PostgreSQL.

11. Verify HTTPS on the Admin Console:

$ curl -sI https://admin.example.com

The output returns HTTP/2 302 with location: /console/welcome on first boot.

12. Verify the OIDC discovery endpoint:

$ curl -s https://auth.example.com/oidc/.well-known/openid-configuration | head -c 200

The output returns JSON containing authorization_endpoint and issuer values scoped to your auth.example.com domain.

2. Access the Admin Console

The Admin Console is the central management interface for configuring the Logto tenant.

Open a web browser and navigate to the Logto Admin Console at https://admin.example.com.
Follow the on-screen instructions to create the initial administrator account, then log in with the new credentials.
Review the sidebar to confirm access to Applications, Sign-in & account, Multi-factor auth, Connectors, Enterprise SSO, API resources, Roles, Organizations, Webhooks, and Audit logs.

3. Configure the Sign-in Experience

The sign-in experience defines the look, feel, and authentication flow for your users.

Set the brand identity: navigate to Sign-in & account and select Branding, upload your logo (for example, https://example.com/logo.png) and set the primary brand color (for example, #6139F6), then click Done.

Configure the email connector: navigate to Connectors and select the Email and SMS connectors tab, click Set up under the Email connector and select SMTP. Obtain the SMTP host, port, username, and password from your email provider, and enter them in the Logto Console:

host: SMTP-HOST
Port: SMTP-PORT
Auth: type: login, user: SMTP-USERNAME, pass: SMTP-PASSWORD
From email: SENDER-EMAIL-ADDRESS
Reply to: REPLY-TO-EMAIL-ADDRESS

Toggle Secure to On if your provider requires TLS, send a test email, then click Save and Done.

Define sign-up identifiers and sign-in methods: on Sign-in & account → Sign-up and sign-in, select sign-up identifiers (Username, Email address, Phone number), configure sign-in methods, and click Save Changes.

Enable passwordless sign-in: on the same tab, enable Email verification code or SMS verification code under Sign-in methods, ensure the corresponding connector is configured, then click Save Changes.

Preview the sign-in UI: click Live preview on the Sign-up and sign-in page to test the branded interface and enabled sign-in methods before applying changes to production traffic.

Logto also supports SMS-based registration and sign-in via third-party providers such as Twilio or Vonage — configure an SMS connector the same way as the email connector. Users access the hosted sign-in UI through a registered application with a valid client_id and redirect URI, not by visiting auth.example.com directly; direct navigation without an application context returns an unknown-session page.

4. Set Up Social Login Connectors

Navigate to Connectors in the left sidebar and select the Social connectors tab, then click Add social connector and select Google.
Create a project in the Google Cloud Console: create a new project, go to APIs & Services → OAuth consent screen, configure the consent screen and add your domain (for example, example.com) as an authorized domain, go to Credentials → Create Credentials → OAuth client ID, select Web application, and add the Logto callback URI (for example, https://auth.example.com/callback/google) to Authorized redirect URIs.
Copy the Client ID and Client Secret from Google and paste them into the Logto social connector configuration.
Configure the Scope field — Logto requests openid, profile, and email by default; append additional scope URLs if the application needs more Google API access.
Click Save and Done, then repeat the process for GitHub and Apple.
On Sign-in & account → Sign-up and sign-in, under Social sign-in, click Add social connector and select the connectors you configured, then Save Changes and test with Live preview.

5. Configure Enterprise SSO

Enterprise Single Sign-On (SSO) enables corporate users to authenticate via their own Identity Provider (IdP), such as Okta or Microsoft Entra ID.

Navigate to Enterprise SSO, click Add enterprise connector, and select Okta (or SAML / OIDC for a generic connector). Use the Connection guide button for provider-specific setup instructions.
In your Okta dashboard, register a new OIDC application, set the Login redirect URI to the value provided by Logto, and obtain the Client ID, Client Secret, and Issuer URL.
Enter these details into the Logto connector configuration and click Save. For SAML connectors, exchange IdP metadata by uploading the metadata file or entering the metadata URL.
On the SSO Experience tab, add the email domains associated with the organization (for example, example.com) — users with matching email domains are automatically routed to the enterprise IdP login page, and other sign-in methods are disabled for those domains.
Enable JIT provisioning to create users automatically on first SSO sign-in, then click Save changes.

6. Enable Multi-Factor Authentication

Navigate to Multi-factor auth in the left sidebar.
Toggle the desired MFA methods to On: Authenticator app (TOTP), WebAuthn / Passkeys (biometric or hardware key), Backup codes, and SMS or Email OTP (requires the corresponding connector).
Configure the MFA Policy (optional MFA or required on every login), then click Save changes.

7. Configure RBAC and API Resources

Navigate to API Resources, click Create API resource, enter an API Name and a unique API Identifier (for example, https://api.example.com/orders), and define Permissions (Scopes) such as read:orders and write:orders.
Navigate to Roles, click Create role, assign the API permissions to the role, and click Save. On the Assign user screen, assign users now or click Skip to assign them later from User management.
If global roles must appear in access tokens, navigate to Custom JWT and configure an access token script to inject role claims into issued JWTs.
Open the API resource you created and click Check guide to view framework-specific integration code (Express, Python, Spring Boot, and others) for initializing the Logto SDK, protecting API routes, and validating the access token.

8. Set Up Organizations for Multi-Tenancy

Organizations offer multi-tenant isolation for B2B applications where users belong to different corporate entities. An organization template is a blueprint defining a consistent set of roles and permissions available to every organization in your Logto tenant.

Navigate to Organization template and create Organization permissions (fine-grained, non-API actions such as read:resource, edit:resource, delete:resource).
Create Organization roles (for example, Admin or Member) and map the permissions to each role.
Navigate to Organizations, click Create organization, select it, and go to the Members tab.
Click Add Members, assign an organization role to each member from the dropdown — Logto scopes JWT tokens to include the organization context when organization-scoped tokens are requested.
Click Check guide to view integration tutorials for multi-tenant features and org-scoped tokens.

9. Register Applications

Register your frontend and backend services as applications within Logto to authenticate users and obtain tokens. Specific steps vary by application type — Single-Page App, Traditional Web App, Native App, or Machine-to-Machine — and the console provides a framework-specific tutorial for each.

Navigate to Applications. If none exist, select a supported framework (React, Next.js, Node.js, and others) and click Start building; otherwise click Create application.
Enter your application name, click Create application, and follow the Jumpstart guide to integrate Logto.
Configure the Redirect URIs and Post Sign-out Redirect URIs, note the App ID and integration endpoint, then click Save changes.

Register at least three application types to cover common architectures: a Single-Page App (SPA) for React/Vue/Angular frontends, a Traditional Web App for server-rendered applications with a backend session, and a Machine-to-Machine (M2M) application for backend services that call the Management API without user interaction. Open the application sign-in URL or use the Logto SDK in a test client to confirm the redirect-based sign-in flow completes successfully.

10. Configure Webhooks

Navigate to Webhooks, click Create webhook, enter the backend Endpoint URL and a descriptive name.
Select the Webhook events to monitor (for example, User.Created, PostSignIn, User.Data.Updated), add optional Custom headers if needed, and click Create webhook.
Use the Signing Key shown in the webhook settings to cryptographically verify that incoming payloads originated from your Logto instance, then send a test payload to confirm the endpoint receives and processes events.

11. Verify the Deployment

Infrastructure: Confirm all containers are running with docker ps — Traefik, Logto, and PostgreSQL should report an Up status.
TLS: Open https://admin.example.com and https://auth.example.com in a browser; both should load with valid Let's Encrypt certificates.
OIDC discovery: Run curl -s https://auth.example.com/oidc/.well-known/openid-configuration and confirm the issuer matches https://auth.example.com/oidc.
Admin Console: Create the initial admin account and confirm the dashboard loads with all sidebar sections.
User registration and sign-in: Register a test user through your application and confirm password-based sign-in works.
Social login, MFA, RBAC, and organizations: Test each configured method end to end — social sign-in through Live preview, MFA enforcement on a test user's next sign-in, an access token containing expected scopes after role assignment, and organization context appearing in the token after adding a user to an organization.
Audit logs: Navigate to Audit logs in the Admin Console and confirm sign-in and configuration events are recorded.

12. Migrate from GCP Identity Platform to Logto

Migrating from GCP Identity Platform to Logto involves mapping Identity Platform Users and Tenants to Logto Organizations and Users, replacing Firebase/GCP Admin SDK calls with Logto SDKs and the Management API, and converting Blocking Functions to webhooks or Custom JWT scripts. Because Identity Platform does not export password hashes or MFA secrets, most migrations follow a bulk user import with mandatory re-authentication strategy. The steps below assume you already completed the deployment, admin console, and application registration sections above.

User migration. GCP Identity Platform bundles user directories, authentication flows, OAuth client configurations, and tenant isolation into a single managed service; Logto splits these across users, the sign-in experience, applications, roles, and organizations.

Export: retrieve user profiles using the Firebase Admin SDK (listUsers()) or the Identity Toolkit API. For multi-tenant projects, iterate through each tenant to export tenant-scoped users.
Import: create users through the Logto Management API (POST /api/users at https://auth.example.com/api), authenticated with an access token from a Logto Machine-to-Machine application.
Passwords: Identity Platform does not expose password hashes — import users with temporary credentials and trigger a password reset on first login.
MFA enrollments: store the original Identity Platform/Firebase localId (UID) in Logto customData (for example, legacy_firebase_uid) to preserve linkages in downstream application databases.

Application migration. If applications use the Firebase Authentication SDK, replace Firebase Auth APIs with the Logto SDK: signInWithEmailAndPassword/signInWithPopup/embedded forms become redirect-based Universal Login; the Firebase API Key/OAuth Client ID becomes the Logto Application ID (client_id); Authorized Domains/Callback URLs become Redirect URIs and Post Sign-out Redirect URIs; token refresh moves to the Logto SDK's session management or standard OIDC refresh flows. If applications call the Identity Toolkit REST API or Firebase Admin SDK directly, replace verifyPassword/verifyCustomToken/signUp with the OIDC authorization code flow (PKCE) or client credentials flow (M2M), getAccountInfo with the OIDC UserInfo endpoint or Management API user lookup, and validate Firebase ID tokens against the Logto JWKS endpoint (https://auth.example.com/oidc/jwks, issuer https://auth.example.com/oidc) instead.

Role and group migration. Identity Platform has no native group primitive — roles are typically assigned via custom claims (setCustomUserClaims) or tenant isolation. Custom claims that gate API access or admin capabilities map to global Logto Roles: create each role (POST /api/roles), define API resource permissions, and assign users (POST /api/users/{userId}/roles) — configure a Custom JWT script to inject role claims, since global roles aren't included by default. Tenant-scoped users representing B2B customers map to Logto Organizations: create the organization (POST /api/organizations), define organization roles in the Organization template, and add members (POST /api/organizations/{id}/users), importing any relational tenant-membership data from Firestore or custom claims. Update backend route guards to parse the claims your Custom JWT script emits instead of Firebase custom claims (for example, decodedToken.admin or decodedToken.tenant_id).

Blocking Function migration. Post-confirmation/post-authentication triggers (async) map to Logto Webhooks (User.Created, PostSignIn, User.Data.Updated). Custom claims and token enrichment map to Custom JWT access token scripts, replacing setCustomUserClaims or blocking-function logic. Pre-authentication/pre-sign-up triggers (sync, blocking) map to application middleware, API gateway rules, or a custom authentication proxy — Logto webhooks cannot block or reject an in-progress sign-in or sign-up synchronously. Custom message triggers map to email/SMS connectors or a webhook consumer. Unlike Cloud Functions, which scale per invocation, Custom JWT scripts run on every token issuance and webhook consumers run as always-on services — plan capacity accordingly.

Data storage considerations. Identity Platform sessions and refresh tokens become invalid at cutover — force re-authentication and clear local Firebase SDK session state (onAuthStateChanged listeners will fire with null). Applications that store Identity Platform localId values rely on the legacy_identity_platform_uid mapping in Logto customData until updated. Replace calls to the Identity Toolkit/Firebase Admin SDK (getUser, listUsers, updateUser) with the Logto Management API at https://auth.example.com/api. Recreate any Identity Platform SAML/OIDC federation as Logto Enterprise SSO or social connectors.

Things to take care of during migration: moving embedded Firebase sign-in forms (signInWithEmailAndPassword, signInWithPopup) and direct Identity Toolkit API calls to redirect-based OIDC is the largest application-code change in most migrations; Identity Platform supports synchronous blocking functions during sign-up and sign-in, but Logto webhooks are asynchronous only, so blocking validation needs application middleware or an API gateway; Identity Platform does not grant end users direct cloud-resource access via IAM roles, so there's no equivalent to migrate away from (a separate Workload Identity Federation setup for backend services is unrelated to end-user auth); Identity Platform's Account Defender has no direct Logto OSS equivalent, so implement rate limiting or WAF rules at the reverse proxy; TOTP secrets and enrolled phone numbers can't be extracted, so users must re-enroll after cutover; Identity Platform ID tokens nest provider and tenant metadata under a firebase claim (sign_in_provider, tenant), while Logto issues standard OIDC claims (sub, email, scope, organization_id); and Identity Platform's tiered per-MAU pricing plus separate SMS/phone-auth charges changes to an infrastructure-based cost model, so calculate total cost of ownership before cutover. Run a phased migration: import users first, validate token flows in a staging tenant, then redirect production traffic to Logto and disable sign-in through the Identity Platform project or tenant.

Next Steps

Configure a Custom JWT script to enrich access tokens with the role and organization claims your applications expect.
Set up organization-scoped applications for each B2B tenant migrating off Identity Platform Tenants.
Add rate limiting or WAF rules at the reverse proxy layer to replace Identity Platform's Account Defender.
Run a staging-tenant migration rehearsal before cutting production traffic over from Identity Platform.

For the full guide with additional tips, visit the original article on Vultr Docs.

Deploying Logto as an AWS Cognito Alternative

Sanskriti Harmukh — Wed, 23 Sep 2026 19:21:55 +0000

AWS Cognito is Amazon's managed authentication service for web and mobile applications, providing User Pools, Identity Pools for federated AWS resource access, a hosted login UI, Lambda triggers, and passwordless sign-in across Lite, Essentials, and Plus tiers. It removes the need to operate an identity store, but it bills per monthly active user (MAU) beyond a free tier of 10,000 MAU that applies only to Lite and Essentials, gates threat protection and adaptive authentication behind the Plus tier (which has no free tier at all), and ties the user directory and its hooks to a specific cloud provider's regions, functions, and IAM. Logto is an open-source Customer Identity and Access Management (CIAM) platform built on OAuth 2.1 and OpenID Connect (OIDC) that covers the same ground on self-hosted infrastructure without per-user billing or cloud provider API dependencies — a branded sign-in experience, social and enterprise SSO federation, multi-factor authentication (MFA), role-based access control (RBAC), organizations for multi-tenancy, and webhooks, all stored in a PostgreSQL database you control. This guide walks through deploying Logto as an alternative to AWS Cognito: the Docker Compose deployment with Traefik and automatic HTTPS, the admin console, sign-in experience and branding, email and social login connectors, enterprise SSO, MFA, RBAC and API resources, organizations, application registration, webhooks, deployment verification, and migration from AWS Cognito. By the end, you'll have a fully configured, self-hosted CIAM platform and a documented path for moving an existing Cognito user base onto it.

Before you begin, you need a Linux-based server with at least 2 CPU cores and 4 GB of RAM as a non-root user with sudo privileges, Docker and Docker Compose installed, and DNS A records pointing to your server's IP address for two subdomains: auth.example.com (Logto Core API and sign-in experience) and admin.example.com (Admin Console).

Understanding Logto Architecture

Logto covers most AWS Cognito components through a self-hosted, OIDC-standard platform. The following table maps each Cognito feature to its Logto counterpart and notes where no equivalent exists.

AWS Cognito	Logto	Description
Cognito User Pools	Logto Users + Sign-in Experience	User management and hosted login pages.
Cognito User Pool SAML and OIDC identity providers	Logto Enterprise SSO Connectors (SAML/OIDC)	Federation with external identity providers.
Cognito Identity Pools	No direct equivalent	Grants access to AWS resources through IAM roles.
Cognito Hosted UI	Logto Sign-in Experience	Fully customizable branded authentication flow.
Cognito Social Providers	Logto Social Connectors	Integration with over 30 social identity providers.
Cognito MFA (SMS, TOTP)	Logto MFA	TOTP, WebAuthn/Passkeys, SMS, Email OTP, and backup codes.
Cognito Lambda Triggers	Logto Webhooks	Asynchronous event-driven webhooks (not inline).
Cognito App Clients	Logto Applications	OIDC clients for SPAs, web apps, and M2M services.
Cognito Groups	Logto Roles + Organizations	Role-based access control and multi-tenant management.
Cognito Advanced Security	No direct equivalent	Use WAF, rate limiting, or a reverse proxy for protection.
AWS Amplify SDKs	Logto SDKs	Official SDKs for over 30 modern development frameworks.

1. Deploy Logto with Docker Compose

1. Create the project directory structure:

$ mkdir -p ~/logto/traefik/letsencrypt

2. Navigate to the project directory:

$ cd ~/logto

3. Create the Logto environment file:

$ nano .env

4. Add the following configuration:

# Domain Configuration
LOGTO_CORE_DOMAIN=auth.example.com
LOGTO_ADMIN_DOMAIN=admin.example.com

# Logto Endpoints
ENDPOINT=https://auth.example.com
ADMIN_ENDPOINT=https://admin.example.com

# SSL Configuration
LETSENCRYPT_EMAIL=admin@example.com

# Database
DB_PASSWORD=DB-PASSWORD

# Logto image version
TAG=1.40.1

# Pins the Docker Engine API version to avoid socket communication errors with newer Traefik releases
DOCKER_API_VERSION=1.54

5. Download the Logto Docker Compose file for the pinned release. Pin the compose file URL to the same release tag as TAG in the environment file — this file is maintained by Logto.

$ wget https://raw.githubusercontent.com/logto-io/logto/v1.40.1/docker-compose.yml

$ nano docker-compose.yml

Find the app service and update the DB_URL under environment:

- DB_URL=postgres://postgres:${DB_PASSWORD}@postgres:5432/logto

Find the postgres service and update POSTGRES_PASSWORD:

POSTGRES_PASSWORD: ${DB_PASSWORD}

Pin the PostgreSQL image to a specific release for reproducible deployments:

image: postgres:17.5-alpine

7. Create the Traefik Docker Compose override file:

$ nano traefik/docker-compose.yml

8. Add the following configuration:

services:
  traefik:
    image: traefik:v3.7.0
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.myresolver.acme.httpchallenge=true"
      - "--certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.myresolver.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.myresolver.acme.storage=/letsencrypt/acme.json"
      - "--entrypoints.web.http.redirections.entryPoint.to=websecure"
      - "--entrypoints.web.http.redirections.entryPoint.scheme=https"
    ports:
      - "80:80"
      - "443:443"
    environment:
      - DOCKER_API_VERSION=${DOCKER_API_VERSION}
      - TRUST_PROXY_HEADER=true
    volumes:
      - ./letsencrypt:/letsencrypt
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      default:
        aliases:
          - ${LOGTO_CORE_DOMAIN}
          - ${LOGTO_ADMIN_DOMAIN}
  app:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.logto-core.rule=Host(`${LOGTO_CORE_DOMAIN}`)"
      - "traefik.http.routers.logto-core.entrypoints=websecure"
      - "traefik.http.routers.logto-core.tls.certresolver=myresolver"
      - "traefik.http.routers.logto-core.service=logto-core"
      - "traefik.http.services.logto-core.loadbalancer.server.port=3001"
      - "traefik.http.routers.logto-admin.rule=Host(`${LOGTO_ADMIN_DOMAIN}`)"
      - "traefik.http.routers.logto-admin.entrypoints=websecure"
      - "traefik.http.routers.logto-admin.tls.certresolver=myresolver"
      - "traefik.http.routers.logto-admin.service=logto-admin"
      - "traefik.http.services.logto-admin.loadbalancer.server.port=3002"

9. Start the Logto stack:

$ docker compose -f docker-compose.yml -f traefik/docker-compose.yml up -d

10. Verify the containers are running:

$ docker ps

The output displays running containers for Traefik, Logto, and PostgreSQL.

11. Verify HTTPS on the Admin Console:

$ curl -sI https://admin.example.com

The output returns HTTP/2 302 with location: /console/welcome on first boot.

12. Verify the OIDC discovery endpoint:

$ curl -s https://auth.example.com/oidc/.well-known/openid-configuration | head -c 200

The output returns JSON containing authorization_endpoint and issuer values scoped to your auth.example.com domain.

2. Access the Admin Console

The Admin Console is the central management interface for configuring the Logto tenant.

Open a web browser and navigate to the Logto Admin Console at https://admin.example.com.
Follow the on-screen instructions to create the initial administrator account, then log in with the new credentials.
Review the sidebar to confirm access to Applications, Sign-in & account, Multi-factor auth, Connectors, Enterprise SSO, API resources, Roles, Organizations, Webhooks, and Audit logs.

3. Configure the Sign-in Experience

The sign-in experience defines the look, feel, and authentication flow for your users.

Set the brand identity: navigate to Sign-in & account in the left sidebar (on first visit, click Get started then Got it), upload your logo (for example, https://example.com/logo.png) and set the primary brand color (for example, #6139F6) under Branding area, then click Done.

host: SMTP-HOST
Port: SMTP-PORT
Auth: type: login, user: SMTP-USERNAME, pass: SMTP-PASSWORD
From email: SENDER-EMAIL-ADDRESS
Reply to: REPLY-TO-EMAIL-ADDRESS

Toggle Secure to On if your provider requires TLS, send a test email, then click Save and Done.

Preview the sign-in UI: click Live preview on the Sign-up and sign-in page to test the branded interface and enabled sign-in methods before applying changes to production traffic.

4. Set Up Social Login Connectors

Navigate to Connectors in the left sidebar and select the Social connectors tab, then click Add Social Connector and select Google.
Create a project in the Google Cloud Console: create a new project, go to APIs & Services → OAuth consent screen, configure the consent screen and add your domain (for example, example.com) as an authorized domain, go to Credentials → Create Credentials → OAuth client ID, select Web application, and add the Logto callback URI (for example, https://auth.example.com/callback/google) to Authorized redirect URIs.
Copy the Client ID and Client Secret from Google and paste them into the Logto social connector configuration.
Configure the Scope field — Logto requests openid, profile, and email by default; append additional scope URLs if the application needs more Google API access.
Click Save and Done, then repeat the process for GitHub and Apple.
On Sign-in & account → Sign-up and sign-in, under Social sign-in, click Add Social Connector and select the connectors you configured, then Save Changes and test with Live preview.

5. Configure Enterprise SSO

Enterprise Single Sign-On (SSO) enables corporate users to authenticate via their own Identity Provider (IdP), such as Okta or Microsoft Entra ID.

Navigate to Enterprise SSO, click Add enterprise connector, and select Okta (or SAML / OIDC for a generic connector). Use the Connection guide button for provider-specific setup instructions.
In your Okta dashboard, register a new OIDC application, set the Login redirect URI to the value provided by Logto, and obtain the Client ID, Client Secret, and Issuer URL.
Enter these details into the Logto connector configuration and click Save. For SAML connectors, exchange IdP metadata by uploading the metadata file or entering the metadata URL.
On the SSO Experience tab, add the email domains associated with the organization (for example, example.com) — users with matching email domains are automatically routed to the enterprise IdP login page, and other sign-in methods are disabled for those domains.
Enable JIT provisioning to create users automatically on first SSO sign-in, then click Save changes.

6. Enable Multi-Factor Authentication

Navigate to Multi-factor auth in the left sidebar.
Toggle the desired MFA methods to On: Authenticator app (TOTP), Passkeys (WebAuthn/biometric/hardware key), Backup codes, and SMS or Email verification code (requires the corresponding connector).
Configure the MFA Policy (optional MFA or required on every login), then click Save changes.

7. Configure RBAC and API Resources

Navigate to API Resources, click Create API resource, enter an API Name and a unique API Identifier (for example, https://api.example.com/orders), and define Permissions (Scopes) such as read:orders and write:orders.
Navigate to Roles, click Create role, assign the API permissions to the role, and click Save. On the Assign user screen, assign users now or click Skip to assign them later from User management.
If global roles must appear in access tokens, navigate to Custom JWT and configure an access token script to inject role claims into issued JWTs.
Open the API resource you created and click Check guide to view framework-specific integration code (Express, Python, Spring Boot, and others) for initializing the Logto SDK, protecting API routes, and validating the access token.

8. Set Up Organizations for Multi-Tenancy

Navigate to Organization template and create Organization permissions (fine-grained, non-API actions such as read:resource, edit:resource, delete:resource).
Create Organization roles (for example, Admin or Member) and map the permissions to each role.
Navigate to Organizations, click Create organization, select it, and go to the Members tab.
Click Add Members, assign an organization role to each member from the dropdown — Logto scopes JWT tokens to include the organization context when organization-scoped tokens are requested.
Click Check guide to view integration tutorials for multi-tenant features and org-scoped tokens.

9. Register Applications

Navigate to Applications. If none exist, select a supported framework (React, Next.js, Node.js, and others) and click Start building; otherwise click Create application.
Enter your application name, click Create application, and follow the Jumpstart guide to integrate Logto.
Configure the Redirect URIs and Post Sign-out Redirect URIs, note the App ID and integration endpoint, then click Save changes.

10. Configure Webhooks

Navigate to Webhooks, click Create webhook, enter the backend Endpoint URL and a descriptive name.
Select the Webhook events to monitor (for example, User.Created, PostSignIn, User.Data.Updated), add optional Custom headers if needed, and click Create webhook.
Use the Signing Key shown in the webhook settings to cryptographically verify that incoming payloads originated from your Logto instance, then send a test payload to confirm the endpoint receives and processes events.

11. Verify the Deployment

Infrastructure: Confirm all containers are running with docker ps — Traefik, Logto, and PostgreSQL should report an Up status.
TLS: Open https://admin.example.com and https://auth.example.com in a browser; both should load with valid Let's Encrypt certificates.
OIDC discovery: Run curl -s https://auth.example.com/oidc/.well-known/openid-configuration and confirm the issuer matches https://auth.example.com/oidc.
Admin Console: Create the initial admin account and confirm the dashboard loads with all sidebar sections.
User registration and sign-in: Register a test user through your application and confirm password-based sign-in works.
Social login, MFA, RBAC, and organizations: Test each configured method end to end — social sign-in through Live preview, MFA enforcement on a test user's next sign-in, an access token containing expected scopes after role assignment, and organization context appearing in the token after adding a user to an organization.
Audit logs: Navigate to Audit logs in the Admin Console and confirm sign-in and configuration events are recorded.

12. Migrate from AWS Cognito to Logto

Migrating from AWS Cognito to Logto involves mapping User Pool resources to Logto tenants, replacing Amplify or Cognito SDK calls with Logto SDKs, and converting Lambda triggers to webhooks or Custom JWT scripts. Because Cognito does not export password hashes or MFA secrets, most migrations follow a bulk user import with mandatory re-authentication strategy. The steps below assume you already completed the deployment, admin console, and application registration sections above.

User migration. An AWS Cognito User Pool bundles user directories, authentication flows, app clients, and groups into a single managed resource; Logto splits these across users, the sign-in experience, applications, roles, and organizations.

Export: retrieve user profiles from Cognito using the AWS CLI (list-users) or the ListUsers API.
Import: create users through the Logto Management API (POST /api/users at https://auth.example.com/api), authenticated with an access token from a Logto Machine-to-Machine application.
Passwords: Cognito does not expose password hashes — import users with temporary credentials and trigger a password reset on first login.
MFA enrollments: TOTP seeds and WebAuthn credentials cannot be exported; users must re-enroll after migration.
Identity mapping: store the original Cognito sub UUID in Logto customData (for example, legacy_cognito_sub) to preserve linkages in downstream application databases.

Application migration. If applications use the AWS Amplify Auth library, replace Amplify Auth APIs with the Logto SDK: signInWithPassword/embedded forms become redirect-based Universal Login; the User Pool App Client ID becomes the Logto Application ID (client_id); Callback URLs become Redirect URIs and Post Sign-out Redirect URIs; token refresh moves to the Logto SDK's session management or standard OIDC refresh flows. If applications call the Cognito API directly, replace InitiateAuth/AdminInitiateAuth with the OIDC authorization code flow (PKCE) or client credentials flow (M2M), GetUser with the OIDC UserInfo endpoint or Management API user lookup, and validate access tokens against the Logto JWKS endpoint (https://auth.example.com/oidc/jwks, issuer https://auth.example.com/oidc) instead of Cognito JWTs.

Role and group migration. Cognito Groups that gate API access or admin capabilities map to global Logto Roles: create each role (POST /api/roles), define API resource permissions, and assign users (POST /api/users/{userId}/roles) — configure a Custom JWT script to inject role claims into access tokens, since global roles aren't included by default. Cognito Groups that represent B2B tenants map to Logto Organizations: create the organization (POST /api/organizations), define organization roles in the Organization template, and add members (POST /api/organizations/{id}/users). Update backend route guards to parse the claims your Custom JWT script emits instead of Cognito's cognito:groups claim.

Lambda trigger migration. Post-confirmation/post-authentication triggers (async) map to Logto Webhooks (User.Created, PostSignIn, User.Data.Updated). Pre-token generation triggers (sync, claims modification) map to Custom JWT access token scripts. Pre-authentication/pre-sign-up triggers (sync, blocking) map to application middleware, API gateway rules, or a custom authentication proxy — Logto webhooks cannot block or reject an in-progress sign-in synchronously. Custom message triggers map to email/SMS connectors or a webhook consumer. Unlike Lambda triggers, which scale per invocation, Custom JWT scripts run on every token issuance and webhook consumers run as always-on services — plan capacity accordingly.

Data storage considerations. Cognito sessions and refresh tokens become invalid at cutover, so force re-authentication and clear local session caches. Applications that store Cognito sub values rely on the legacy_cognito_sub mapping in Logto customData until updated. Replace calls to Cognito IDP endpoints (AdminGetUser, ListUsers, AdminUpdateUserAttributes) with the Logto Management API at https://auth.example.com/api. Recreate any Cognito SAML/OIDC federation as Logto Enterprise SSO or social connectors.

Things to take care of during migration: moving embedded Amplify sign-in forms to redirect-based OIDC is the largest application-code change in most migrations; Logto webhooks are asynchronous only, so blocking validation needs middleware or a gateway; Cognito Identity Pools (AWS resource access via IAM) have no Logto equivalent, so provide access through M2M API gateways, role assumption, or application-level credentials; Cognito Advanced Security has no direct Logto OSS equivalent, so implement rate limiting or WAF rules at the reverse proxy; MFA secrets can't be extracted, so users must re-enroll; Cognito's custom claims (cognito:groups, cognito:username) differ from Logto's standard OIDC claims (sub, email, scope); Hosted UI CSS customization maps to Logto sign-in experience branding, though complex custom login pages need a custom UI built on the Logto SDK; and Cognito's per-MAU pricing changes to an infrastructure-based cost model, so calculate total cost of ownership before cutover. Run a phased migration: import users first, validate token flows in a staging tenant, then redirect production traffic to Logto and disable the Cognito User Pool.

Next Steps

Configure a Custom JWT script to enrich access tokens with the role and organization claims your applications expect.
Set up organization-scoped applications for each B2B tenant migrating off Cognito Groups.
Add rate limiting or WAF rules at the reverse proxy layer to replace Cognito Advanced Security.
Run a staging-tenant migration rehearsal before cutting production traffic over from Cognito.

For the full guide with additional tips, visit the original article on Vultr Docs.

Deploying Ory Hydra: An Open-Source OAuth 2.0 and OpenID Connect Server

Sanskriti Harmukh — Wed, 23 Sep 2026 19:20:47 +0000

Ory Hydra is an open-source OAuth 2.0 Authorization Server and OpenID Connect (OIDC) provider. Unlike identity platforms that bundle user management, Hydra delegates authentication to a separate login and consent application that you control, and it handles the OAuth 2.0 authorization code flow, client credentials flow, token introspection, and token revocation through an API-first architecture that separates the authorization protocol from identity storage. This guide walks through deploying Ory Hydra on a Linux server using Docker Compose with PostgreSQL, Nginx, and a Java-based login and consent application. By the end, you'll have a working OAuth 2.0/OIDC server with its admin API bound to the loopback interface and a full authorization code flow you can test end to end.

Before you begin, you need a Linux-based server with at least 2 CPU cores and 4 GB of RAM as a non-root user with sudo privileges, Docker and Docker Compose installed, and a DNS A record pointing to your server's IP address (for example, hydra.example.com).

1. Set Up the Directory Structure, Configuration, and Environment Variables

Ory Hydra reads its configuration from a YAML file and reads database credentials and secrets from environment variables at runtime. The directory structure separates the Hydra configuration, the Nginx reverse proxy configuration, and the TLS certificate storage into distinct paths.

1. Create the project directory with all required subdirectories:

$ mkdir -p ~/ory-hydra/{config/nginx,data/{postgres,certbot/conf}}

config/ stores the Hydra configuration file and the Nginx server configuration, data/postgres/ persists PostgreSQL database files across container restarts, and data/certbot/conf/ stores the Let's Encrypt TLS certificate files.

2. Navigate to the project directory:

$ cd ~/ory-hydra

3. Clone the Java reference login and consent application into the project directory:

$ git clone https://github.com/ardetrick/ory-hydra-refrence-java.git reference-app

If you have your own application that implements the Hydra login and consent protocol, skip this step and replace ./reference-app in the Docker Compose file with your application's source directory.

4. Generate a system secret for signing tokens and encrypting database records (Hydra requires at least 16 characters). Run this command twice:

$ openssl rand -hex 16

Use the first output as YOUR_SYSTEM_SECRET and the second as YOUR_PAIRWISE_SALT (the OIDC pairwise subject identifier salt). The system secret is written into hydra.yml for reference, but the SECRETS_SYSTEM environment variable defined in .env takes precedence at runtime because Docker Compose passes it directly to the Hydra container — replace YOUR_SYSTEM_SECRET in both files with the same generated value to keep them consistent.

5. Create the Hydra configuration file:

$ nano config/hydra.yml

6. Add the following content, replacing hydra.example.com with your domain name, YOUR_SYSTEM_SECRET with the first generated value, and YOUR_PAIRWISE_SALT with the second:

serve:
  public:
    base_url: https://hydra.example.com/
    cors:
      enabled: true
      allowed_origins:
        - https://hydra.example.com
      allowed_methods:
        - POST
        - GET
        - PUT
        - DELETE
      allowed_headers:
        - Authorization
        - Content-Type
      exposed_headers:
        - Content-Type
      allow_credentials: true
  admin:
    base_url: http://127.0.0.1:4445/

urls:
  self:
    issuer: https://hydra.example.com/
  login: https://hydra.example.com/login
  consent: https://hydra.example.com/consent
  logout: https://hydra.example.com/logout

secrets:
  system:
    - YOUR_SYSTEM_SECRET

oidc:
  subject_identifiers:
    supported_types:
      - public
      - pairwise
    pairwise:
      salt: YOUR_PAIRWISE_SALT

strategies:
  access_token: opaque

ttl:
  login_consent_request: 30m
  access_token: 1h
  refresh_token: 720h
  id_token: 1h
  auth_code: 10m

log:
  level: info
  format: text
  leak_sensitive_values: false

serve.public sets the public API base URL and restricts CORS to your domain. serve.admin declares the admin API base URL — the actual network restriction is enforced by the Docker Compose port binding (127.0.0.1:4445:4445), which limits the admin API to the loopback interface. urls tells Hydra where to redirect users during login and consent. secrets.system signs access tokens and encrypts sensitive database records; changing it invalidates all existing tokens. strategies.access_token: opaque means tokens are random strings validated through the introspection endpoint (the alternative, jwt, allows stateless validation but cannot be revoked before expiry). ttl configures token lifetimes, and log disables sensitive value exposure in log output. The admin API base_url uses http://127.0.0.1:4445/ intentionally — the admin API accepts and rejects login and consent requests without authentication and must never be exposed through the public reverse proxy.

7. Create the Nginx configuration file:

$ nano config/nginx/default.conf

8. Add the following content, replacing all instances of hydra.example.com with your actual domain name:

server {
    listen 80;
    server_name hydra.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name hydra.example.com;

    ssl_certificate /etc/letsencrypt/live/hydra.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/hydra.example.com/privkey.pem;

    resolver 127.0.0.11 valid=30s;

    # Callback page for the OAuth 2.0 authorization code flow
    location = /callback {
        root /etc/nginx/html;
        try_files /callback.html =404;
    }

    # Login and consent app routes
    location ~ ^/(login|consent|logout|demo) {
        set $login_consent hydra:8080;
        proxy_pass http://$login_consent;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Hydra public OAuth 2.0 and OIDC endpoints
    location / {
        set $hydra hydra:4444;
        proxy_pass http://$hydra;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

The first server block redirects all HTTP traffic to HTTPS. The second listens on 443 with TLS and contains three location blocks: /callback serves the static callback HTML page directly; ^/(login|consent|logout|demo) routes to the login and consent app on port 8080; and / routes everything else to the Hydra public API on port 4444, covering the authorization endpoint, token endpoint, revocation endpoint, and the /.well-known/openid-configuration discovery document. Because all services run on the same Docker network, Nginx resolves the hydra hostname through Docker's internal DNS — the resolver 127.0.0.11 valid=30s directive is required when using variables in proxy_pass directives. The X-Forwarded-Proto header ensures Hydra recognizes that the original client connection uses HTTPS, which is required for secure redirect generation and cookie handling.

9. Create the callback page that displays the authorization code after a successful OAuth 2.0 flow:

$ nano config/nginx/callback.html

10. Add the following content:

<!DOCTYPE html>
<html>
<head>
  <title>OAuth2 Callback</title>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/vue/3.4.0/vue.global.prod.min.js"></script>
</head>
<body>
<div id="app">
  <div v-if="error">
    <h2>Authorization Failed</h2>
    <p><strong>Error:</strong> {{ error }}</p>
    <p><strong>Reason:</strong> {{ errorDesc }}</p>
  </div>
  <div v-else-if="code">
    <h2>Authorization Successful</h2>
    <p><strong>Code:</strong> <code>{{ code }}</code></p>
    <pre>{{ curlCmd }}</pre>
  </div>
  <div v-else>
    <h2>No code or error received.</h2>
  </div>
</div>
<script>
const { createApp } = Vue;
const params = new URLSearchParams(window.location.search);
const code = params.get("code");
const error = params.get("error");
const errorDesc = params.get("error_description");
const origin = window.location.origin;

createApp({
  data() {
    return {
      code,
      error,
      errorDesc,
      curlCmd: code ? [
        "curl -X POST " + origin + "/oauth2/token \\",
        "  -H 'Content-Type: application/x-www-form-urlencoded' \\",
        "  -d 'grant_type=authorization_code' \\",
        "  -d 'code=" + code + "' \\",
        "  -d 'redirect_uri=" + origin + "/callback' \\",
        "  -d 'client_id=YOUR_CLIENT_ID' \\",
        "  -d 'client_secret=YOUR_CLIENT_SECRET'"
      ].join("\n") : ""
    };
  }
}).mount("#app");
</script>
</body>
</html>

The callback page reads the code and error query parameters from the URL and renders the result using Vue. On a successful flow, it displays the authorization code and a ready-to-run curl command to exchange it for tokens; on a failed flow, it displays the error and reason returned by Hydra.

11. Create the environment variables file:

$ nano .env

12. Add the following content, replacing EXAMPLE_DB_PASSWORD with a strong, unique database password and YOUR_SYSTEM_SECRET with the same value you placed in config/hydra.yml:

HYDRA_VERSION=v26.2.0
POSTGRES_USER=hydra
POSTGRES_PASSWORD=EXAMPLE_DB_PASSWORD
POSTGRES_DB=hydradb
SECRETS_SYSTEM=YOUR_SYSTEM_SECRET
LOG_LEVEL=info

2. Deploy with Docker Compose

Docker Compose manages all services as a single deployment unit. Certbot runs once as a standalone container to obtain the initial TLS certificate before Nginx starts, which requires port 80 to be free at that point.

1. Create the Docker Compose file:

$ nano docker-compose.yml

2. Add the following content:

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    networks:
      - hydra-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M

  hydra-migrate:
    image: oryd/hydra:${HYDRA_VERSION}
    environment:
      - DSN=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable
    command: migrate sql -e --yes
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - hydra-network
    restart: on-failure
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 256M

  hydra:
    image: oryd/hydra:${HYDRA_VERSION}
    ports:
      - "127.0.0.1:4445:4445"
    environment:
      - DSN=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable
      - SECRETS_SYSTEM=${SECRETS_SYSTEM}
      - LOG_LEVEL=${LOG_LEVEL}
    command: serve all --config /etc/config/hydra/hydra.yml
    volumes:
      - ./config:/etc/config/hydra
    depends_on:
      hydra-migrate:
        condition: service_completed_successfully
    networks:
      - hydra-network
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M

  hydra-login-consent:
    build:
      context: ./reference-app
      dockerfile_inline: |
        FROM gradle:8-jdk21 AS build
        WORKDIR /app
        COPY . .
        ENV GRADLE_OPTS="-Xmx256m -Xms64m -Dfile.encoding=UTF-8"
        RUN gradle bootJar --no-daemon

        FROM eclipse-temurin:21-jre
        WORKDIR /app
        COPY --from=build /app/reference-app/build/libs/*.jar app.jar
        ENTRYPOINT ["java", "-jar", "-Xmx200m", "-Xms64m", "app.jar"]
    depends_on:
      - hydra
    network_mode: "service:hydra"
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 512M

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./config/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
      - ./data/certbot/conf:/etc/letsencrypt:ro
      - ./config/nginx/callback.html:/etc/nginx/html/callback.html:ro
    depends_on:
      - hydra
      - hydra-login-consent
    networks:
      - hydra-network
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 128M

networks:
  hydra-network:
    driver: bridge

postgres stores OAuth 2.0 clients, authorization codes, tokens, and consent records, with a pg_isready health check gating dependent services. hydra-migrate runs database migrations once and exits with code 0; hydra waits for that exit before starting. hydra runs serve all, starting the public API on port 4444 and the admin API on port 4445 — the admin port is bound to 127.0.0.1 on the host, restricting it to the loopback interface. The SECRETS_SYSTEM environment variable overrides the value in hydra.yml at runtime. hydra-login-consent builds the Java reference app via a multi-stage Gradle and Eclipse Temurin build and, using network_mode: "service:hydra", shares Hydra's network namespace to reach the admin API at 127.0.0.1:4445. nginx terminates TLS and is the only service that exposes ports to the host. All services connect to a shared hydra-network bridge network, and each includes a deploy.resources.limits block capping CPU and memory. The PostgreSQL DSN uses sslmode=disable because the connection travels over the internal Docker bridge network; if you move PostgreSQL to a separate host, change this to sslmode=require and configure TLS on the PostgreSQL server.

3. Run Certbot as a Docker container in standalone mode to get a TLS certificate from Let's Encrypt, replacing admin@example.com and hydra.example.com with your own values:

$ docker run --rm -p 80:80 \
    -v ~/ory-hydra/data/certbot/conf:/etc/letsencrypt \
    certbot/certbot certonly --standalone \
    --non-interactive --agree-tos --no-eff-email \
    --email admin@example.com \
    -d hydra.example.com

4. Check that the certificate files exist, replacing hydra.example.com with your domain name:

$ sudo ls ~/ory-hydra/data/certbot/conf/live/hydra.example.com/

Verify that the output lists fullchain.pem, privkey.pem, chain.pem, cert.pem, and README.

5. Create the certificate renewal script:

$ nano ~/ory-hydra/renew-cert.sh

6. Add the following content:

#!/usr/bin/env bash
set -euo pipefail

cd ~/ory-hydra
docker compose stop nginx
docker run --rm -p 80:80 \
    -v ~/ory-hydra/data/certbot/conf:/etc/letsencrypt \
    certbot/certbot renew --non-interactive
docker compose start nginx

Save and close the file, then make it executable:

$ chmod +x ~/ory-hydra/renew-cert.sh

7. Open the crontab editor:

$ crontab -e

If this is the first time you run crontab -e, the system prompts you to select an editor from a numbered list. Enter the number corresponding to /bin/nano or your preferred editor.

8. Add the following line to run the renewal script at 3:00 a.m. on the 1st and 15th of every month:

0 3 1,15 * * /bin/bash ~/ory-hydra/renew-cert.sh >> ~/ory-hydra/renew-cert.log 2>&1

Let's Encrypt certificates expire after 90 days, so running the job twice a month keeps the certificate updated. Certbot only renews certificates that expire within 30 days, so running the script twice a month is safe, and a transient failure on the 1st is retried on the 15th.

9. Start all services in detached mode:

$ docker compose up -d

Wait about 30 seconds for the database to initialize and migrations to complete.

10. Check the status of all containers:

$ docker compose ps -a

Verify that postgres, hydra, hydra-login-consent, and nginx all show Up, and that hydra-migrate shows Exited (0).

11. Check the Hydra logs to confirm that the server started without errors:

$ docker compose logs hydra | grep "Setting up http server"

Verify that the output contains two lines showing Hydra listening on 0.0.0.0:4444 and 0.0.0.0:4445. If you see database connection errors, wait a few seconds and restart the Hydra container:

$ docker compose restart hydra

3. Verify the Deployment and Test the Authorization Code Flow

Hydra exposes a public API on port 4444 for OAuth 2.0 and OIDC requests, and an admin API on port 4445 for client management, accessible only from the server through the loopback port binding.

1. Test the Hydra admin API health endpoint from the server:

$ curl -s http://127.0.0.1:4445/health/alive

A successful response returns {"status":"ok"}.

2. Test the public API through the Nginx HTTPS reverse proxy, replacing hydra.example.com with your domain name:

$ curl -s https://hydra.example.com/health/alive

3. Verify that the OpenID Connect discovery document is accessible, replacing hydra.example.com with your domain name:

$ curl -s https://hydra.example.com/.well-known/openid-configuration

Verify that the response contains a JSON document with the issuer, authorization_endpoint, token_endpoint, and jwks_uri fields.

4. Register a new OAuth 2.0 client using the Hydra CLI inside the running container, replacing hydra.example.com with your domain name:

$ docker compose exec hydra hydra create oauth2-client \
    --endpoint http://127.0.0.1:4445 \
    --format json \
    --grant-type authorization_code,refresh_token \
    --response-type code \
    --scope openid,offline_access,profile \
    --redirect-uri https://hydra.example.com/callback \
    --token-endpoint-auth-method client_secret_post \
    --name "My Test App"

The response is a JSON object containing the registered client. Copy the client_id and client_secret values. The offline_access scope requests a refresh token alongside the access token; the openid scope triggers Hydra to issue an ID token identifying the authenticated user.

5. Open a web browser and navigate to the authorization URL below, replacing both instances of hydra.example.com with your domain name and CLIENT_ID with the client_id from the previous step:

https://hydra.example.com/oauth2/auth?response_type=code&client_id=CLIENT_ID&redirect_uri=https://hydra.example.com/callback&scope=openid+offline_access+profile&state=random-state-value

Hydra checks for an active session and, finding none, redirects the browser to the login page.

6. On the login page, enter the demo credentials below and click Log in:

email: foo@bar.com
password: password

The login app accepts the challenge through the Hydra admin API and redirects the browser to the consent page.

7. On the consent page, review the requested scopes and click Allow access. The consent app accepts the challenge and Hydra redirects the browser to https://hydra.example.com/callback with the authorization code in the code query parameter.

8. The callback page displays the authorization code and a ready-to-run curl command to exchange it for tokens. Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET in the displayed command with the values from client registration, then run the command from your server terminal. A successful response returns a JSON object containing an access_token, refresh_token, and id_token. Copy the access_token value.

9. Introspect the access token to confirm that it is active, replacing ACCESS_TOKEN with the access token from the previous step:

$ curl -s -X POST http://127.0.0.1:4445/admin/oauth2/introspect \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'token=ACCESS_TOKEN'

A valid, active token returns a JSON response with "active": true, the sub field containing the authenticated user's identifier, the scope field listing the granted scopes, and token metadata including iss, iat, and exp.

Next Steps

Replace the Java reference login and consent app with your own implementation, backed by your real user directory.
Configure additional OAuth 2.0 clients for each application that needs tokens from this server.
Switch strategies.access_token to jwt if you need stateless validation and can accept the revocation trade-off.
Set up centralized logging and alerting on the Hydra and Nginx containers for production monitoring.

For the full guide with additional tips, visit the original article on Vultr Docs.

Deploying LiteLLM: An Open-Source AI Gateway

Sanskriti Harmukh — Wed, 23 Sep 2026 19:19:19 +0000

LiteLLM is an open-source AI gateway that provides a unified, OpenAI-compatible API for over 100 large language model (LLM) providers, removing the need to integrate with each provider's SDK and authentication scheme. In production, teams use LiteLLM to issue virtual keys with budget limits, track token usage and spend across providers, and configure centralized access control and routing. This guide walks through deploying LiteLLM on a Linux server using Docker Compose with PostgreSQL for persistent storage, Prometheus for metrics collection, and Traefik as the reverse proxy for HTTPS access. By the end, you'll have a fully functional, OpenAI-compatible AI gateway accessible over a custom domain, with virtual key management, spend tracking, and provider routing configured.

Before you begin, you need a Linux-based server with at least 4 CPU cores and 8 GB of RAM as a non-root user with sudo privileges, Docker and Docker Compose installed, a DNS A record (such as litellm.example.com) pointing to your server's IP address, and an API key from at least one supported LLM provider.

1. Set Up the Directory Structure, Configuration, and Environment Variables

LiteLLM requires a configuration file to define model providers and routing rules, a Prometheus configuration file for metrics scraping, and environment variables for secrets and database credentials.

1. Create the project directory with subdirectories for persistent data:

$ mkdir -p ~/litellm/{letsencrypt,postgres,prometheus}

letsencrypt stores SSL/TLS certificates, postgres persists PostgreSQL database files, and prometheus persists Prometheus metrics data.

2. Navigate to the project directory:

$ cd ~/litellm

3. Set matching ownership on the Prometheus host directory (Prometheus runs as UID 65534 inside the container):

$ sudo chown -R 65534:65534 prometheus

4. Generate a master key and salt key for LiteLLM. Run this command twice to produce two separate values:

$ openssl rand -hex 32

Save both values for the LITELLM_MASTER_KEY and LITELLM_SALT_KEY fields in the next step.

5. Create the .env file to store credentials and secrets:

$ nano .env

6. Add the following values:

DOMAIN=litellm.example.com
LETSENCRYPT_EMAIL=admin@example.com
LITELLM_MASTER_KEY=sk-YOUR_MASTER_KEY
LITELLM_SALT_KEY=sk-YOUR_SALT_KEY
LLM_PROVIDER_API_KEY=YOUR_LLM_PROVIDER_API_KEY
POSTGRES_PASSWORD=STRONG_DATABASE_PASSWORD
DATABASE_URL=postgresql://llmproxy:${POSTGRES_PASSWORD}@db:5432/litellm
UI_USERNAME=admin
UI_PASSWORD=YOUR_UI_PASSWORD

Replace the placeholders with your own values: litellm.example.com is the domain pointing to your server's IP address; admin@example.com is the email address for Let's Encrypt notifications; sk-YOUR_MASTER_KEY is the admin key used to authenticate with the LiteLLM API (replace YOUR_MASTER_KEY with the first generated value and keep the sk- prefix); sk-YOUR_SALT_KEY encrypts provider credentials stored in PostgreSQL and cannot be changed after the first model is added; YOUR_LLM_PROVIDER_API_KEY is the API key for the provider configured in config.yaml; STRONG_DATABASE_PASSWORD is the PostgreSQL password used by both the database container and the connection string; admin/YOUR_UI_PASSWORD are the LiteLLM dashboard credentials.

7. Create the LiteLLM configuration file:

$ nano config.yaml

8. Add the following contents:

model_list:
  - model_name: my-model
    litellm_params:
      model: provider/model
      api_key: os.environ/LLM_PROVIDER_API_KEY

litellm_settings:
  callbacks:
    - prometheus
  require_auth_for_metrics_endpoint: true

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

Replace my-model with a name of your choice to identify this model within LiteLLM, and provider/model with the LiteLLM provider prefix followed by the model identifier (for example, anthropic/claude-haiku-4-5). The os.environ/ prefix tells LiteLLM to read the value from an environment variable at runtime rather than hardcoding it. The litellm_settings block enables Prometheus metrics via the callbacks field, and require_auth_for_metrics_endpoint: true restricts the /metrics endpoint to authenticated requests, so only Prometheus (sending the master key as a Bearer token) can scrape metrics successfully. The general_settings block defines the master key LiteLLM uses to authenticate admin API requests and virtual key management operations.

9. Create the Prometheus configuration file:

$ nano prometheus.yml

10. Add the following contents:

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: "litellm"
    static_configs:
      - targets: ["litellm:4000"]
    bearer_token: "sk-YOUR_MASTER_KEY"

Replace sk-YOUR_MASTER_KEY with the value of LITELLM_MASTER_KEY from your .env file. Prometheus uses this token to authenticate its scrape requests against the protected /metrics endpoint.

2. Deploy with Docker Compose

The deployment stack runs LiteLLM behind Traefik, which handles TLS termination and automatic certificate provisioning through Let's Encrypt. PostgreSQL provides persistent storage for virtual keys, spend data, and usage logs. Prometheus collects gateway metrics by scraping the LiteLLM /metrics endpoint every 15 seconds over the internal Docker network.

1. Add your user account to the Docker group:

$ sudo usermod -aG docker $USER

2. Apply the new group membership:

$ newgrp docker

3. Create the Docker Compose manifest file:

$ nano docker-compose.yaml

4. Add the following contents:

services:
  traefik:
    image: traefik:v3.6
    container_name: traefik
    restart: always
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--certificatesresolvers.le.acme.httpchallenge=true"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt

  litellm:
    image: docker.litellm.ai/berriai/litellm:v1.89.1
    container_name: litellm
    restart: always
    volumes:
      - ./config.yaml:/app/config.yaml
    command:
      - "--config=/app/config.yaml"
    environment:
      DATABASE_URL: ${DATABASE_URL}
      STORE_MODEL_IN_DB: "True"
    env_file:
      - .env
    expose:
      - "4000"
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test:
        - CMD-SHELL
        - python3 -c "import urllib.request; urllib.request.urlopen('http://localhost:4000/health/liveliness')"
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.litellm.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.litellm.entrypoints=websecure"
      - "traefik.http.routers.litellm.tls=true"
      - "traefik.http.routers.litellm.tls.certresolver=le"
      - "traefik.http.services.litellm.loadbalancer.server.port=4000"

  db:
    image: postgres:16
    container_name: litellm_db
    restart: always
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: llmproxy
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./postgres:/var/lib/postgresql/data
    expose:
      - "5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d litellm -U llmproxy"]
      interval: 1s
      timeout: 5s
      retries: 10

  prometheus:
    image: prom/prometheus
    container_name: litellm_prometheus
    restart: always
    volumes:
      - ./prometheus:/prometheus
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    expose:
      - "9090"
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.path=/prometheus"
      - "--storage.tsdb.retention.time=15d"

This configuration deploys four services behind a single HTTPS endpoint: traefik acts as the reverse proxy and TLS terminator, redirecting HTTP to HTTPS via Let's Encrypt; litellm runs the proxy image pinned to a specific release tag, mounts config.yaml, and waits for PostgreSQL to become healthy before starting; db runs PostgreSQL 16 as the persistent backend for virtual keys, spend data, and usage logs; prometheus scrapes LiteLLM metrics every 15 seconds with a 15-day retention window. The named volumes for db and prometheus ensure their data survives container removal or recreation.

Verify the Docker Image with Cosign

LiteLLM Docker images are signed with Cosign. Verifying the image signature before deployment confirms the image has not been tampered with since it was published by the LiteLLM team.

1. Download and install the Cosign binary:

$ curl -O -L "https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64"

2. Move the binary into your system path:

$ sudo mv cosign-linux-amd64 /usr/local/bin/cosign

3. Make the binary executable:

$ sudo chmod +x /usr/local/bin/cosign

4. Verify the installation:

$ cosign version

5. Verify the LiteLLM image signature using the pinned public key. This checks the same release tag deployed in the Docker Compose file. LiteLLM publishes signatures for the ghcr.io registry specifically, so this confirms the v1.89.1 release itself, not the docker.litellm.ai mirror byte-for-byte.

$ cosign verify \
    --key https://raw.githubusercontent.com/BerriAI/litellm/0112e53046018d726492c814b3644b7d376029d0/cosign.pub \
    ghcr.io/berriai/litellm:v1.89.1

A successful verification outputs a JSON payload confirming the image was signed with the LiteLLM public key.

Start the Stack

1. Start the services:

$ docker compose up -d

2. Verify all containers are running:

$ docker compose ps

Verify that all four containers show an Up status, with litellm and db marked (healthy) and traefik listing ports 80 and 443 under PORTS.

3. Access and Configure LiteLLM

LiteLLM exposes a web-based admin dashboard at the /ui path of your configured domain, with visibility into model configuration, virtual keys, usage, and spend tracking.

Open your web browser and navigate to https://litellm.example.com/ui, replacing litellm.example.com with your configured domain.
Log in using the credentials from your .env file — the value of UI_USERNAME in the Username field and UI_PASSWORD in the Password field, then click Login. Verify that the dashboard loads and displays the main navigation panels.
Click Models + Endpoints in the left sidebar to verify the configured model providers. The model defined in config.yaml appears in the list with its alias and underlying provider model. The left sidebar also provides access to Virtual Keys for managing scoped access credentials, Usage for per-model and per-key request tracking, and Logs for spend and cost breakdowns by model, key, and team.

4. Test the Gateway and Create a Virtual Key

LiteLLM exposes an OpenAI-compatible API, so any application built for the OpenAI SDK works with LiteLLM by pointing base_url at the gateway. Virtual keys provide scoped, credential-isolated access without exposing the master key.

1. Install the Python virtual environment package:

$ sudo apt install -y python3-venv

2. Create a Python virtual environment:

$ python3 -m venv litellm-env

3. Activate the virtual environment:

$ source litellm-env/bin/activate

4. Install the OpenAI Python SDK:

$ pip install openai

5. Export your master key as an environment variable, replacing sk-YOUR_MASTER_KEY with the LITELLM_MASTER_KEY value from your .env file:

$ export LITELLM_MASTER_KEY="sk-YOUR_MASTER_KEY"

6. Export your gateway domain as an environment variable, replacing litellm.example.com with your configured domain:

$ export LITELLM_DOMAIN="litellm.example.com"

7. Create the test script:

$ nano test_litellm.py

8. Add the following contents, replacing my-model with the model name you set in config.yaml:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LITELLM_MASTER_KEY"],
    base_url=f"https://{os.environ['LITELLM_DOMAIN']}",
)

response = client.chat.completions.create(
    model="my-model",
    messages=[{"role": "user", "content": "What is an AI gateway?"}],
)

print(response.choices[0].message.content)

9. Run the script:

$ python3 test_litellm.py

The script returns a response from the configured LLM provider, confirming the gateway is routing requests correctly.

10. Create a virtual key using the LiteLLM API, replacing my-model with the model name you set in config.yaml:

$ curl -X POST "https://${LITELLM_DOMAIN}/key/generate" \
    -H "Authorization: Bearer ${LITELLM_MASTER_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"key_alias": "test-app-key", "models": ["my-model"], "max_budget": 5.00}' \
    | python3 -c "import sys, json; print(json.load(sys.stdin)['key'])"

The command prints the generated virtual key, similar to sk-M9M0_aUDLi7AuhXtOAw6uw. Each key can have its own model access list, budget limit, and rate limit.

11. Export the virtual key returned in the previous step, replacing sk-your-virtual-key with the full key string printed:

$ export LITELLM_VIRTUAL_KEY="sk-your-virtual-key"

12. Send a request using the virtual key, replacing my-model with the model name you set in config.yaml:

$ curl -X POST "https://${LITELLM_DOMAIN}/v1/chat/completions" \
    -H "Authorization: Bearer ${LITELLM_VIRTUAL_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "my-model",
      "messages": [{"role": "user", "content": "Hello from a virtual key!"}]
    }'

The gateway authenticates the virtual key, routes the request to the configured provider, and returns the model response.

13. Return to the dashboard at https://litellm.example.com/ui and click Logs in the left sidebar. Each entry shows the model alias, key alias, token count, and estimated cost for requests sent through both the master key and the virtual key.

Next Steps

Add more models to config.yaml and issue per-team or per-application virtual keys with distinct budget limits.
Build Grafana dashboards on top of the Prometheus metrics for gateway observability.
Set up alerting on budget thresholds and failed provider requests.
Rotate the master key and salt key periodically and re-verify Docker image signatures on every upgrade.

For the full guide with additional tips, visit the original article on Vultr Docs.

Deploying Langflow: An Open-Source Visual Framework for Building AI Applications

Sanskriti Harmukh — Wed, 23 Sep 2026 19:16:50 +0000

Langflow is an open-source, low-code visual framework for building artificial intelligence (AI) agents, workflows, and retrieval-augmented generation (RAG) applications. Developers use its visual builder to assemble large language model (LLM) pipelines from prebuilt components and test them in an interactive Playground, and finished flows run as API endpoints or Model Context Protocol (MCP) servers without extra boilerplate code. This guide walks through self-hosting a production-ready Langflow instance on a Linux server with Docker Compose, covering PostgreSQL persistence, Traefik reverse proxying with automatic HTTPS certificates, authentication for the visual editor, and validation of the deployment through a RAG chatbot that answers questions from an uploaded document. By the end, you'll have a secured Langflow deployment running behind HTTPS with a working RAG chatbot proving that ingestion, retrieval, and generation all work end to end.

Before you begin, you need a Linux-based server with at least 2 CPU cores and 4 GB of RAM as a non-root user with sudo privileges, Docker and Docker Compose installed, a domain A record pointing to the server's public IP address (for example, langflow.example.com), and an API key from a supported LLM provider — this deployment uses OpenAI models for embeddings and chat responses.

1. Set Up the Project Directory and Environment

Langflow reads its runtime configuration from environment variables, so a dedicated project directory with a .env file keeps credentials out of the Compose manifest.

1. Create the project directory and switch into it:

$ mkdir ~/langflow && cd ~/langflow

2. Generate a Langflow secret key and write it to the environment file:

$ python3 -c "from secrets import token_urlsafe; print(f'LANGFLOW_SECRET_KEY={token_urlsafe(32)}')" >> .env

Langflow encrypts stored credentials with this Fernet key. Without an explicit key, Langflow generates a random one at startup and encrypted values become unreadable after a restart.

3. Verify that the file contains the key without displaying its value:

$ grep -c "LANGFLOW_SECRET_KEY" .env

Output:

4. Open the .env file with a text editor such as nano:

$ nano .env

5. Add the following variables below the existing LANGFLOW_SECRET_KEY line, replacing every placeholder with your own values:

# Domain and certificate settings
LANGFLOW_HOSTNAME=langflow.example.com
LETSENCRYPT_EMAIL=admin@example.com

# PostgreSQL credentials
POSTGRES_USER=langflow
POSTGRES_PASSWORD=DATABASE_PASSWORD
POSTGRES_DB=langflow

# Langflow storage paths
LANGFLOW_CONFIG_DIR=/app/langflow
LANGFLOW_KNOWLEDGE_BASES_DIR=/app/langflow/knowledge_bases

# Authentication settings
LANGFLOW_AUTO_LOGIN=False
LANGFLOW_SUPERUSER=administrator
LANGFLOW_SUPERUSER_PASSWORD=ADMIN_PASSWORD
LANGFLOW_NEW_USER_IS_ACTIVE=False
LANGFLOW_ENABLE_SUPERUSER_CLI=False

# LLM provider credentials
OPENAI_API_KEY=OPENAI_API_KEY

LANGFLOW_HOSTNAME and LETSENCRYPT_EMAIL supply the domain for the Traefik routing rule and the contact address for certificate expiry notices. The POSTGRES_* variables initialize the database container on first boot and are reused in the Langflow connection string — use only letters and numbers in the password, because symbols require %-encoding and $ conflicts with Compose interpolation. LANGFLOW_CONFIG_DIR and LANGFLOW_KNOWLEDGE_BASES_DIR place application data and knowledge base vectors on the same volume-mapped path; without the second variable, Langflow writes knowledge bases outside that volume and a container replacement deletes your vector data. LANGFLOW_AUTO_LOGIN=False disables anonymous access, LANGFLOW_SUPERUSER/LANGFLOW_SUPERUSER_PASSWORD define the administrator account Langflow creates at startup, LANGFLOW_NEW_USER_IS_ACTIVE=False keeps new accounts inactive until approved, and LANGFLOW_ENABLE_SUPERUSER_CLI=False blocks superuser creation from the command line. OPENAI_API_KEY supplies the LLM provider credential, which Langflow stores as an encrypted global variable.

6. Restrict the environment file so only its owner can read or modify it:

$ chmod 600 .env

2. Deploy with Docker Compose

The stack runs three services. Traefik terminates HTTPS, Langflow serves the application on internal port 7860, and PostgreSQL stores flows, users, and settings. Langflow joins the proxy network with Traefik and the internal network with PostgreSQL, so the database stays unreachable from outside.

1. Create the docker-compose.yml file in the project directory:

$ nano docker-compose.yml

2. Add the following service definitions to the file:

services:
  traefik:
    image: traefik:v3.7
    restart: unless-stopped
    command:
      - --providers.docker=true
      - --providers.docker.exposedbydefault=false
      - --providers.docker.network=proxy
      - --entryPoints.web.address=:80
      - --entryPoints.websecure.address=:443
      - --entryPoints.websecure.http.tls=true
      - --entryPoints.web.http.redirections.entryPoint.to=websecure
      - --entryPoints.web.http.redirections.entryPoint.scheme=https
      - --certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}
      - --certificatesresolvers.le.acme.storage=/letsencrypt/acme.json
      - --certificatesresolvers.le.acme.httpchallenge.entrypoint=web
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt
    networks:
      - proxy

  langflow:
    image: langflowai/langflow:1.11.3
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      - LANGFLOW_DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      - LANGFLOW_CONFIG_DIR=${LANGFLOW_CONFIG_DIR}
      - LANGFLOW_KNOWLEDGE_BASES_DIR=${LANGFLOW_KNOWLEDGE_BASES_DIR}
      - LANGFLOW_AUTO_LOGIN=${LANGFLOW_AUTO_LOGIN}
      - LANGFLOW_SUPERUSER=${LANGFLOW_SUPERUSER}
      - LANGFLOW_SUPERUSER_PASSWORD=${LANGFLOW_SUPERUSER_PASSWORD}
      - LANGFLOW_SECRET_KEY=${LANGFLOW_SECRET_KEY}
      - LANGFLOW_NEW_USER_IS_ACTIVE=${LANGFLOW_NEW_USER_IS_ACTIVE}
      - LANGFLOW_ENABLE_SUPERUSER_CLI=${LANGFLOW_ENABLE_SUPERUSER_CLI}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - langflow-data:/app/langflow
    networks:
      - proxy
      - internal
    labels:
      - traefik.enable=true
      - traefik.http.routers.langflow.rule=Host(`${LANGFLOW_HOSTNAME}`)
      - traefik.http.routers.langflow.entrypoints=websecure
      - traefik.http.routers.langflow.tls.certresolver=le
      - traefik.http.services.langflow.loadbalancer.server.port=7860

  postgres:
    image: postgres:16-trixie
    restart: unless-stopped
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 10
    volumes:
      - langflow-postgres:/var/lib/postgresql/data
    networks:
      - internal
networks:
  proxy:
    name: proxy
  internal:

volumes:
  langflow-data:
  langflow-postgres:

The traefik service publishes ports 80 and 443, discovers only explicitly labeled containers through the read-only Docker socket, and registers a certificate resolver named le that completes the ACME challenge on port 80 and redirects plain HTTP to HTTPS. The langflow service pins the langflowai/langflow:1.11.3 image; the Traefik labels route your domain to port 7860 inside the container, and the langflow-data volume persists LANGFLOW_CONFIG_DIR across restarts. The postgres service pins postgres:16-trixie, joins only the internal network, and its pg_isready health check gates the Langflow start.

3. Start the stack in detached mode:

$ docker compose up -d

4. Verify that all containers are running:

$ docker compose ps

The output displays three running containers, with Traefik listening on ports 80 and 443 and PostgreSQL reporting a healthy status.

5. Check the Langflow logs to verify that the application started:

$ docker compose logs -f langflow

The first start takes a few minutes because Langflow runs its database migrations against PostgreSQL. The log stream ends with a startup banner when the application is ready.

Output:

Open Langflow → http://localhost:7860

Press Ctrl+C to stop following the logs. The localhost address applies inside the container only, and Traefik forwards your domain traffic to the same listener.

3. Access and Configure Langflow

The stack now runs behind HTTPS, so the remaining configuration happens in the browser.

Open a web browser and visit your Langflow domain, such as https://langflow.example.com. Traefik requests a Let's Encrypt certificate after the stack starts — if the browser shows a certificate warning, wait a minute and reload. Because automatic login is off, Langflow redirects you to the /login page.
Log in with the values you set for LANGFLOW_SUPERUSER and LANGFLOW_SUPERUSER_PASSWORD. The Langflow Projects page opens.
Verify the model provider: click your profile icon in the header, select Settings, then Model Providers. OpenAI appears as configured because Langflow detects the OPENAI_API_KEY variable at startup. Enable the models you plan to use under Language Models and Embedding Models.
Verify the stored credential: in Settings, click Global Variables. A variable named OPENAI_API_KEY appears with the Credential type, which masks its value in the visual editor.

4. Build a RAG Chatbot to Validate the Deployment

A RAG chatbot answers questions from your own documents instead of relying only on the model's training data. Langflow ships a Vector Store RAG template that pairs a retrieval flow with a knowledge base, which chunks a document, embeds it, and stores the vectors locally. A grounded answer in the Playground proves that ingestion, retrieval, and generation all work on the deployed stack.

Create a Knowledge Base from a Sample Document

On the Projects page, click Knowledge below the list of projects, then click Add Knowledge.
In the Create Knowledge Base pane, enter a name such as langflow_demo, select an OpenAI embedding model, and keep Chroma Local as the DB Provider — it stores vectors on the server, so the knowledge base requires no external database account.
Click Add Files and select a document from your local machine, such as a product manual or a policy document.
Keep the default values for Chunk Size, Chunk Overlap, and Separator, then click Next Step.
Review the sample chunk in the Review & Build pane, then click Create. Langflow splits the document into chunks, converts each chunk into a vector, and indexes the results.
Wait until the knowledge base Status changes to Ready, which means the ingestion pipeline completed without errors.

Create the Flow from the Vector Store RAG Template

On the Projects page, click New Flow, then select the Vector Store RAG template.
Review how the components connect: Chat Input sends each question to Knowledge as the Search Query and to Prompt as the {question} variable. Knowledge returns matching chunks, Parser extracts their text, and Prompt inserts that text as {context}. Agent generates the answer, and Chat Output returns it.
In the Knowledge component, keep Retrieve as the Mode, and select your langflow_demo knowledge base. Retrieval reuses the embedding model from ingestion, so query vectors and stored vectors stay comparable.
In the Agent component, select an OpenAI chat model in the Language Model field. The template preloads Agent Instructions with a retrieval-focused system prompt.
Review the Prompt component. Adjust the wording if you want a different tone, but keep the {context} and {question} placeholders intact.

Test the Chatbot in the Playground

Click Playground. A chat panel opens.
Type a question that only your uploaded document can answer, then press Enter.
Read the response — the flow runs a semantic search against the knowledge base, pulls the most similar chunks, and instructs the language model to answer from that context.
Ask a follow-up question about a different part of the document to verify that retrieval covers the full file rather than a single chunk.

Next Steps

Add more LLM providers (Anthropic, Gemini, and others) as global variables and swap models per flow.
Explore other Langflow templates for agents and multi-step pipelines.
Publish a flow as an API endpoint or MCP server to power a downstream application.
Set up scheduled PostgreSQL backups to protect your flow and knowledge base data.

For the full guide with additional tips, visit the original article on Vultr Docs.

Deploying Metabase - Open-Source Business Intelligence Tool

Sanskriti Harmukh — Wed, 23 Sep 2026 19:12:08 +0000

Metabase is an open-source business intelligence (BI) tool that lets you explore data, build dashboards, and share reports from a web browser. Teams often self-host it because it connects to common databases such as PostgreSQL, MySQL, MariaDB, and SQL Server. This guide deploys Metabase on a Linux server using Docker Compose with a PostgreSQL backend and Traefik providing automatic HTTPS, covering directory and environment setup, deployment, and the initial administrator setup through the web interface. By the end, you'll have Metabase running securely at your domain, ready to connect data sources and build dashboards.

Set Up the Project Directory and Environment Variables

Metabase stores its application data, such as users, dashboards, and saved questions, in PostgreSQL. This section creates the project directory and the environment file that the Compose stack shares.

1. Create the project directory and move into it:

$ mkdir ~/metabase
$ cd ~/metabase

2. Generate a random key that Metabase uses to encrypt stored data-source credentials:

$ openssl rand -base64 32

Save the output for use in the environment file.

3. Create the environment file:

$ nano .env

Add the following configuration. Replace YOUR_DB_PASSWORD with a strong password, YOUR_ENCRYPTION_KEY with the output from the previous openssl command, metabase.example.com with your domain name, and ADMIN_EMAIL with a deliverable email address for Let's Encrypt renewal notices.

POSTGRES_DB=metabaseappdb
POSTGRES_USER=metabase
POSTGRES_PASSWORD=YOUR_DB_PASSWORD
MB_ENCRYPTION_SECRET_KEY=YOUR_ENCRYPTION_KEY
MB_SITE_URL=https://metabase.example.com
DOMAIN=metabase.example.com
ACME_EMAIL=ADMIN_EMAIL

Save and close the file.

Deploy with Docker Compose

The deployment stack consists of Traefik for reverse proxy and certificate management, plus the Metabase and PostgreSQL containers on a shared bridge network. This configuration uses the official Metabase container image version v0.50.21.

1. Create the Docker Compose manifest:

$ nano docker-compose.yml

services:
  postgres:
    image: postgres:16
    container_name: metabase-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    mem_limit: 1g
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - metabase-network

  metabase:
    image: metabase/metabase:v0.50.21
    container_name: metabase
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      MB_DB_TYPE: postgres
      MB_DB_DBNAME: ${POSTGRES_DB}
      MB_DB_PORT: 5432
      MB_DB_USER: ${POSTGRES_USER}
      MB_DB_PASS: ${POSTGRES_PASSWORD}
      MB_DB_HOST: postgres
      MB_ENCRYPTION_SECRET_KEY: ${MB_ENCRYPTION_SECRET_KEY}
      MB_SITE_URL: ${MB_SITE_URL}
    healthcheck:
      test: ["CMD", "curl", "--fail", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 120s
    mem_limit: 2g
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - metabase-network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.metabase.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.metabase.entrypoints=websecure"
      - "traefik.http.routers.metabase.tls.certresolver=letsencrypt"
      - "traefik.http.services.metabase.loadbalancer.server.port=3000"

  traefik:
    image: traefik:v3.7.10
    container_name: traefik
    restart: unless-stopped
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.letsencrypt.acme.email=${ACME_EMAIL}"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
      - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt
    networks:
      - metabase-network

volumes:
  postgres-data:

networks:
  metabase-network:
    driver: bridge

Save and close the file. postgres runs PostgreSQL 16 as the database storing Metabase's users, dashboards, and saved questions. metabase runs the application server, starting only after PostgreSQL reports healthy, with Traefik labels registering it for automatic HTTPS on the configured DOMAIN. traefik handles reverse proxying and TLS termination on ports 80 and 443. mem_limit and logging cap each container's memory and rotate its logs, preventing either from exhausting the server's resources.

2. Launch the containers:

$ docker compose up -d

3. Verify that the services are running:

$ docker compose ps -a

The output displays all three containers in an Up state, with a healthy status shown for metabase-postgres and metabase once their health checks pass.

4. Query the Metabase health endpoint through your domain:

$ curl https://metabase.example.com/api/health

Your output should be similar to the one below:

{"status":"ok"}

5. View the service logs to confirm Metabase loaded the configuration successfully:

$ docker compose logs -f metabase

The output displays PostgreSQL accepting connections and Metabase completing its startup migrations, which take one to two minutes. Press Ctrl+C to stop following the logs once the service reports that it has started.

Access Metabase and Complete the Initial Setup

Open Metabase in a browser and complete the first-run wizard.

Open your domain over HTTPS in a browser. Replace metabase.example.com with your domain:

   https://metabase.example.com

Select your preferred language.
Create the initial administrator account by entering your name, email address, and password.
When prompted to add your first data source, configure one now or skip and add it later.

Setup is now complete, and Metabase is ready to use. Any databases you connect through the interface stay separate from the PostgreSQL container, which stores only Metabase's own metadata.

Next Steps

Metabase is live with Traefik-managed HTTPS and a PostgreSQL-backed metadata store. From here you can:

Connect your production databases and start building dashboards and saved questions
Configure user groups and permissions to control who can see which data
Set up scheduled email or Slack reports (pulses) so dashboards reach stakeholders automatically

For the full guide with additional tips, visit the original article on Vultr Docs.

Installing Composer with PHP

Sanskriti Harmukh — Wed, 16 Sep 2026 17:13:04 +0000

Composer is the standard tool for managing PHP dependencies. It automates library installation, enforces version constraints, and helps organize autoloading, making it an essential part of modern PHP development. Whether you're building with frameworks like Laravel, Symfony, or Slim, Composer ensures consistency across environments and simplifies dependency resolution. This guide covers installing Composer with a specific PHP version on a Linux system — useful when working across multiple PHP projects or servers that require different runtime versions. By the end, you'll have Composer installed safely, bound to a specific PHP version such as PHP 8.4, and a reusable alias set up for scripting or interactive use.

Prerequisites

Access to a Linux instance.
SSH access to the server.
A non-root user with sudo privileges.
The server's package index already updated.

Install PHP

Install PHP, the command-line interface (CLI), and required tools such as curl and unzip using your distribution's package manager.

Install PHP on Ubuntu and Debian

1. Install the default PHP version and required utilities on APT-based systems:

$ sudo apt install -y php php-cli curl unzip

To install a specific PHP version (such as 8.3 or 8.4), add a third-party repository — the Ondřej Surý PPA on Ubuntu, or the SURY repository on Debian. These repositories provide maintained versions of PHP not available in the default APT sources.

Install PHP on Rocky Linux and AlmaLinux

1. Install PHP and required tools on DNF-based distributions:

$ sudo dnf install -y php php-cli curl unzip

To install a specific PHP version, enable the EPEL and Remi repositories. These repositories offer multiple PHP versions for RHEL-based systems including Rocky Linux and AlmaLinux.

Install Composer Using a Specific PHP Version

Note: This guide uses PHP 8.4 as the example version. On DNF-based distributions (like Rocky Linux or AlmaLinux), the system uses php as the command unless update-alternatives is configured. If php8.4 doesn't work, use php instead.

1. Download the Composer installer using PHP 8.4:

$ php8.4 -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

2. Get the installer signature. This ensures the installer is authentic and has not been tampered with:

$ curl -s https://composer.github.io/installer.sig

Copy the hash from the output. You'll need it for verification in the next step.

3. Verify the installer. Replace your_hash_here with the hash you copied:

$ php8.4 -r "if (hash_file('sha384', 'composer-setup.php') === 'your_hash_here') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"

Output:

Installer verified

4. Run the Composer installer using PHP 8.4 and install it system-wide:

$ sudo php8.4 composer-setup.php --install-dir=/usr/local/bin --filename=composer

5. Clean up the installer file:

$ rm composer-setup.php

6. Verify the Composer installation:

$ composer

Output:

    ______
   / ____/___  ____ ___  ____  ____  ________  _____
  / /    / __ \/ __ `__ \/ __ \/ __ \/ ___/ _ \/ ___/
 / /___/ /_/ / / / / / / /_/ / /_/ (__  )  __/ /
 \____/\____/_/ /_/ /_/ .___/\____/____/\___/_/
                     /_/
Composer version 2.8.8 2025-04-04 16:56:46

Run Composer with a Specific PHP Version

To run Composer with a specific PHP version (like PHP 8.4), configure your environment as follows.

1. Confirm the path of the PHP 8.4 binary:

$ which php8.4

Output:

/usr/bin/php8.4

2. Run Composer using the PHP 8.4 binary:

$ php8.4 /usr/local/bin/composer

3. Create an alias so composer always runs with PHP 8.4 (optional):

$ echo 'alias composer="php8.4 /usr/local/bin/composer"' >> ~/.bashrc

For portability in scripts or cron jobs, consider using a shebang like #!/usr/bin/env php instead of hardcoding a version path.

4. Reload your shell configuration to apply the alias:

$ source ~/.bashrc

If you're using Zsh, replace ~/.bashrc with ~/.zshrc.

5. Verify that Composer now runs with PHP 8.4:

$ composer --version

Output:

Composer version 2.8.8 2025-04-04 16:56:46
PHP version 8.4.0 (/usr/bin/php8.4)
Run the "diagnose" command to get more detailed diagnostics output.

For managing multiple Composer versions or isolating global dependencies per PHP version, consider tools like cgr, composer-bin, or asdf.

Test Composer Functionality (Optional)

To confirm that Composer is functional and can generate project scaffolding:

1. Run composer init in non-interactive mode to generate a minimal composer.json:

$ composer init --name=test/app --description="Test app" --author="Your Name" --require=php:^8.4 --no-interaction

2. View the generated file to confirm success:

$ cat composer.json

Output:

{
    "name": "test/app",
    "description": "Test app",
    "require": {
        "php": "^8.4"
    }
}

You can now run composer install or add additional dependencies to begin building your PHP project.

Next Steps

You now have Composer installed on your Linux system, bound to a specific PHP version such as PHP 8.4, with a reusable alias for convenience. From here, you can:

Run composer require to add your first dependencies to a real project
Set up global tool isolation or multi-version workflows with cgr, composer-bin, or asdf
Add Composer's vendor/ directory to your .gitignore and commit composer.lock for reproducible installs
Read the official Composer documentation to learn more about autoloading and dependency constraints

For the full guide with additional tips, visit the original article on Vultr Docs.

Installing Ruby on Ubuntu 24.04

Sanskriti Harmukh — Wed, 16 Sep 2026 17:12:37 +0000

Ruby is a dynamic, object-oriented programming language perfect for creating basic scripts to complex web applications. It offers a modern syntax for productivity, runs with an interpreter instead of a compiler, and provides a wide range of frameworks for various projects. This guide covers installing Ruby on Ubuntu 24.04 using rbenv, RVM, and APT. By the end, you'll have a working Ruby installation, with the option to manage and switch between multiple Ruby versions on the same server.

Install Ruby Using rbenv

rbenv is a Ruby version manager that lets you install multiple versions of Ruby and switch between them.

1. Install all required dependencies for the ruby-build plugin to download and compile Ruby:

$ sudo apt install autoconf patch build-essential rustc libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libgmp-dev libncurses5-dev libffi-dev libgdbm6 libgdbm-dev libdb-dev libtool uuid-dev

2. Install the latest rbenv installation script:

$ curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash

3. Add the rbenv path to the .bashrc file:

$ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc

4. Reload the .bashrc shell configuration to apply the path changes in your active session:

$ source ~/.bashrc

5. View the installed rbenv version:

$ rbenv -v

Your output should be similar to the one below:

rbenv 1.3.0-9-gefeab7f

6. List all available Ruby versions you can install:

$ rbenv install -l

Note the target Ruby version in your output similar to the one below:

3.1.6
3.2.6
3.3.6
jruby-9.4.9.0
mruby-3.3.0
picoruby-3.0.0
truffleruby-24.1.1
truffleruby+graalvm-24.1.1

Only latest stable releases for each Ruby implementation are shown.
Use `rbenv install --list-all' to show all local versions.

7. Install your target Ruby version. For example, 3.3.6:

$ rbenv install 3.3.6

The installation process may take 3-5 minutes to complete depending on the available server resources.

8. Set the installed Ruby version as the default if the installation is successful:

$ rbenv global 3.3.6

9. View the installed Ruby version:

$ ruby --version

Your output should be similar to the one below:

ruby 3.3.6 (2024-11-05 revision 75015d4c1f) [x86_64-linux]

Install Ruby Using RVM

Ruby Version Manager (RVM), also known as Ruby environment manager, is a command-line tool used to install, manage, and work with multiple Ruby environments on a server.

1. Install the required GPG keys for RVM:

$ gpg --keyserver keyserver.ubuntu.com --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB

2. Install RVM:

$ curl -sSL https://get.rvm.io | bash -s

3. Load RVM into your shell environment:

$ source ~/.rvm/scripts/rvm

4. List and install all the RVM system requirements:

$ rvm requirements

Enter your sudo user password when prompted to update the server's package index. Your output should be similar to the one below:

Checking requirements for ubuntu.
Installing requirements for ubuntu.
.....................
Installing required packages: autoconf, automake, bison, libffi-dev, libgdbm-dev, libsqlite3-dev, libtool, libyaml-dev, sqlite3, libgmp-dev, libncurses-dev, libreadline-dev, libssl-dev...............
Requirements installation successful.

5. View the installed RVM version:

$ rvm -v

Your output should be similar to the one below:

rvm 1.29.12-next (master) by Michal Papis, Piotr Kuczynski, Wayne E. Seguin [https://rvm.io]

6. List the available Ruby versions you can install:

$ rvm list known

Note the target Ruby version in your output similar to the one below:

# MRI Rubies
[ruby-]1.8.6[-p420]
[ruby-]1.8.7[-head] # security released on head
[ruby-]1.9.1[-p431]
[ruby-]1.9.2[-p330]
[ruby-]1.9.3[-p551]
[ruby-]2.0.0[-p648]
[ruby-]2.1[.10]
[ruby-]2.2[.10]
[ruby-]2.3[.8]
[ruby-]2.4[.10]
[ruby-]2.5[.9]
[ruby-]2.6[.10]
[ruby-]2.7[.8]
[ruby-]3.0[.7]
[ruby-]3.1[.5]
[ruby-]3.2[.6]
[ruby-]3[.3.6]
[ruby-]3.4[.0-preview1]
ruby-head
............

7. Install a specific Ruby version. For example, 3.3.6:

$ rvm install 3.3.6

8. Set the installed Ruby version as the default:

$ rvm --default use 3.3.6

9. View all installed Ruby versions:

$ rvm list

Your output should be similar to the one below:

=* ruby-3.3.6 [ x86_64 ]

# => - current
# =* - current && default
#  * - default

Install Ruby Using APT

Ruby is available in the default APT package manager repositories, but the included version is not the latest.

1. Update the server's package index:

$ sudo apt update

2. Install Ruby:

$ sudo apt install ruby-full

3. View the installed Ruby version:

$ ruby --version

Your output should be similar to the one below:

ruby 3.2.3 (2024-01-18 revision 52bb2ac0a6) [x86_64-linux-gnu]

Uninstall Ruby

1. Uninstall a specific Ruby version using rbenv. For example, 3.3.6:

$ rbenv uninstall 3.3.6

2. Remove a specific Ruby version using RVM:

$ rvm remove 3.3.6

3. Uninstall Ruby installed using APT:

$ sudo apt autoremove ruby-full

Next Steps

You now have Ruby installed on Ubuntu 24.04 using rbenv, RVM, and/or APT, with the ability to install and switch between multiple Ruby versions. From here, you can:

Install a Ruby framework such as Rails or Sinatra to start building web applications
Set a per-project Ruby version with a .ruby-version file when using rbenv or RVM
Set up bundler to manage gem dependencies for your projects
Review the RVM Documentation or rbenv Manual Page for advanced version management

For the full guide with additional tips, visit the original article on Vultr Docs.