Deploying on Poddle

Welcome to the Poddle deployment guide. Poddle makes it seamless to deploy your backend APIs, frontend apps, and connect them securely without dealing with complex infrastructure.

Navigating the Dashboard

To get started, head to the Poddle console:

Look at the left sidebar and select your project from the Projects dropdown.
Once a project is selected, the main page will display your existing deployment cards.
To start a new deployment, click the Create Deployment button located in the top right corner.

Creating a Deployment

When you click Create Deployment, a dialog popup will appear with two main tabs:

Container Image: Deploy a prebuilt container image from a public or private registry.
Github Repository: Deploy directly from your source code.

Deploying from GitHub

In the Github Repository tab, select your repository from the dropdown list. If your GitHub account isn't connected yet, click the Install GitHub button to authorize Poddle.

Once your repository is selected, you can choose your build method:

Auto-detect: Poddle will automatically detect your language/framework and build the app for you.
Dockerfile: Use your own Dockerfile for custom environments and builds.

Note: Both the Auto-detect and Dockerfile methods fully support continuous integration and deployment (CI/CD) out of the box.

Port Configuration (Crucial)

Whether you are deploying a backend or a frontend, configuring the correct port is required for your app to be reachable.

Important: The port your application actively listens on must perfectly match the Container Port specified in the deployment creation dialog.

Hardcoded Ports: If your server code is hardcoded to listen on port 8080, you must enter 8080 in the Container Port field in the Poddle dialog.
Dynamic Ports: You can use whatever environment variables you prefer to set your port dynamically in your code. Just ensure the final resolved port matches the Container Port you configure in Poddle.

Tracing and Observability

Poddle has built-in observability capabilities. Whenever you deploy, Poddle automatically injects the OTEL_EXPORTER_OTLP_ENDPOINT environment variable into your container.

If you instrument your code with OpenTelemetry, your application will automatically route data to Poddle. This allows you to effortlessly leverage the built-in Tracing feature in your dashboard without setting up any extra infrastructure.

Deploying a Frontend

For most static sites and Single Page Applications (SPAs) like Next.js, Remix, Vite, Tanstack Start, Astro, React Router, or Nuxt, Poddle handles the deployment automatically. Simply select the Auto-detect method, and Poddle will build and serve your frontend.

Connecting Frontend and Backend

If your project includes both a frontend and a backend, your frontend needs a way to communicate with the backend. Poddle supports two common approaches.

Method 1: Public Address (Domain/Subdomain)

The simplest approach is to attach a public domain or Poddle subdomain directly to your backend deployment. Your frontend then makes requests to that public URL.

// Frontend code — points directly at the backend's public domain
const API_URL = 'https://sfs-backend.poddle.uz';

fetch(`${API_URL}/items`);

This is easy to set up, but it exposes your backend to the public internet, meaning anyone can reach it directly.

Method 2: Internal Nginx Proxy (Recommended for Security)

If you want to keep your backend completely private and only reachable within your projects, you can use an Nginx reverse proxy. Your frontend container serves your static files and forwards API calls to the backend.

Here is how this architecture works under the hood:

Relative Requests: In your frontend code, you make a relative fetch call (e.g., fetch('/api/items')). The browser sends this to your Nginx container.
Internal Service Discovery: Poddle runs on Kubernetes, which provides internal DNS. Nginx forwards the request using your backend's internal service name (e.g., app-abc123). This name is invisible to the public internet, keeping your backend secure.
Dynamic Configuration: To avoid hardcoding internal URLs, Nginx uses an nginx.conf.template. When the container starts, a built-in tool called envsubst automatically replaces placeholders (like ${BACKEND_URL}) with the actual environment variables provided by Poddle.

The Trailing Slash Behavior (Crucial)

When configuring Nginx, the way you write the proxy_pass URL dictates how the path is forwarded to your backend.

With a trailing slash (proxy_pass http://backend/):
- Nginx performs a prefix substitution. It strips the matched location block (e.g., /api/) and appends the rest of the path.
- Incoming: /api/items 👉 Forwarded as: http://backend/items
Without a trailing slash (proxy_pass http://backend):
- Nginx appends the entire original path.
- Incoming: /api/items 👉 Forwarded as: http://backend/api/items Ensure you choose the behavior that matches the routes expected by your backend API.

Setting Up the Nginx Proxy

To set this up, you will deploy your frontend using the Dockerfile method with a custom Nginx configuration.

1. Create nginx.conf.template in your frontend repository:

server {
    listen ${PORT};

    # Serve the frontend static files
    location / {
        root /usr/share/nginx/html;
        index index.html;
        try_files $uri /index.html;
    }

    # Proxy API requests to the backend
    # You can change '/api/' to whatever prefix your frontend uses (e.g., '/v1/', '/backend/').
    # Note the trailing slash on both the location and the proxy_pass
    location /api/ {
        proxy_pass ${BACKEND_URL};
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

2. Create a Dockerfile for your frontend:

FROM node:24-alpine AS build

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install
COPY . .
RUN npm run build

FROM nginx:alpine

# Nginx automatically processes this template and injects Poddle's env vars
COPY nginx.conf.template /etc/nginx/templates/default.conf.template
COPY --from=build /app/dist /usr/share/nginx/html

3. Configure Environment Variables in Poddle: When creating the frontend deployment in Poddle, set the following environment variables:

PORT: (Match this with your Container Port in the dialog)
BACKEND_URL: http://<your-backend-internal-service-name>:<port>/ (Include the trailing slash if your backend routes do not include /api (so Nginx strips the prefix). Omit it if your backend already expects /api in the path.)

Your frontend is now securely proxying API requests to your private backend using Poddle's internal network.

Deployment Guide