Skip to main content
Tabby AI Keyboard has two backend services with fully automated deployment pipelines: a Python backend on Azure Container Apps and a Next.js shared API backend on Vercel.

​
Python Backend (Azure Container Apps)

The Python backend provides memory and AI processing services, deployed to Azure Container Apps with automated CI/CD.

​
Deployment Overview

​
Prerequisites

1

Configure Azure resources

Create the following Azure resources:
  • Resource Group: tabby-rg (or your preferred name)
  • Container App: tabby-backend
  • Container Apps Environment: Required for running the container app
You can create these via Azure Portal or Azure CLI. The deployment workflow assumes these resources already exist.
2

Set up GitHub Secrets

Add these secrets to your GitHub repository (Settings → Secrets and variables → Actions):
Secret NameDescription
DOCKER_USERNAMEYour Docker Hub username
DOCKER_PASSWORDYour Docker Hub password or access token
AZURE_CREDENTIALSAzure service principal credentials (JSON)
For AZURE_CREDENTIALS, you need to create a service principal with contributor access to your resource group. See Azure documentation for details.

​
Docker Configuration

The backend uses a multi-stage Python 3.12 Dockerfile (backend/Dockerfile:1-24): 
# Use Python 3.12 slim image
FROM python:3.12-slim

# Set working directory
WORKDIR /app

# Install uv for fast dependency management
RUN pip install uv

# Copy dependency files
COPY pyproject.toml uv.lock ./

# Install dependencies
RUN uv sync --frozen --no-dev

# Copy application code
COPY main.py .

# Expose the port
EXPOSE 8000

# Run the application
CMD ["uv", "run", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
Key features:
  • Uses uv for fast dependency management
  • Python 3.12 slim base image for minimal size
  • Runs uvicorn ASGI server on port 8000
  • Production-ready with --frozen dependency installation

​
Deployment Workflow

The Azure deployment workflow automatically triggers when: 
on:
  push:
    branches: [main]
    paths:
      - "backend/**"
      - ".github/workflows/backend-deploy.yml"
  workflow_dispatch:
1

Build Docker image

The workflow builds a Docker image using buildx with caching:
- name: Build and push Docker image
  uses: docker/build-push-action@v5
  with:
    context: ./backend
    push: true
    tags: |
      thecubestar/tabby-backend:latest
      thecubestar/tabby-backend:${{ github.sha }}
    cache-from: type=gha
    cache-to: type=gha,mode=max
Each build creates two tags:
  • latest: Points to the most recent build
  • <git-sha>: Immutable tag for the specific commit
2

Push to Docker Hub

The image is pushed to Docker Hub repository thecubestar/tabby-backend.
3

Deploy to Azure

The Azure Container App is updated with the new image:
- name: Deploy to Azure Container Apps
  uses: azure/CLI@v1
  with:
    inlineScript: |
      az containerapp update \
        --name tabby-backend \
        --resource-group tabby-rg \
        --image thecubestar/tabby-backend:${{ github.sha }}
This performs a zero-downtime rolling update.

​
Environment Variables

The workflow sets these environment variables: 
env:
  IMAGE_NAME: thecubestar/tabby-backend
  AZURE_CONTAINER_APP: tabby-backend
  AZURE_RESOURCE_GROUP: tabby-rg
Modify these values in .github/workflows/backend-deploy.yml if you use different resource names.

​
Manual Deployment

To deploy manually:
1

Build Docker image locally

cd backend
docker build -t thecubestar/tabby-backend:manual .
2

Push to Docker Hub

docker push thecubestar/tabby-backend:manual
3

Update Azure Container App

az containerapp update \
  --name tabby-backend \
  --resource-group tabby-rg \
  --image thecubestar/tabby-backend:manual

​
Next.js Backend (Vercel)

The Next.js shared API backend provides common API endpoints, deployed to Vercel.

​
Deployment Overview

  • Platform: Vercel
  • Workflow: .github/workflows/vercel-deploy.yml
  • Production URL: tabby-api-psi.vercel.app
  • Trigger: Push to nextjs-backend/ directory on main branch

​
Prerequisites

1

Create Vercel project

  1. Sign in to Vercel
  2. Create a new project from your repository
  3. Set the root directory to nextjs-backend
  4. Note the Organization ID and Project ID
2

Generate Vercel token

  1. Go to Settings → Tokens in Vercel dashboard
  2. Create a new token with appropriate scopes
  3. Save the token securely
3

Configure GitHub Secrets

Add these secrets to your repository:
Secret NameDescription
VERCEL_TOKENYour Vercel authentication token
ORG_IDYour Vercel organization ID
PROJECT_IDYour Vercel project ID
GH_TOKENGitHub token for workflow operations

​
Deployment Workflow

The Vercel deployment workflow (.github/workflows/vercel-deploy.yml:1-22) automatically deploys on changes: 
on:
  push:
    branches: [main]
    paths:
      - "nextjs-backend/**"
      - ".github/workflows/vercel-deploy.yml"
  workflow_dispatch:
1

Checkout code

- uses: actions/checkout@v4
2

Deploy to Vercel

- uses: amondnet/vercel-action@v20
  with:
    vercel-token: ${{ secrets.VERCEL_TOKEN }}
    github-token: ${{ secrets.GH_TOKEN }}
    vercel-args: "--prod"
    vercel-org-id: ${{ secrets.ORG_ID}}
    vercel-project-id: ${{ secrets.PROJECT_ID}}
    working-directory: nextjs-backend
The --prod flag ensures deployment to production (not preview).

​
Environment Variables in Vercel

Configure environment variables in Vercel dashboard:
  1. Go to your project Settings → Environment Variables
  2. Add required variables for your Next.js backend
  3. Set appropriate environments (Production, Preview, Development)
Environment variables set in Vercel are separate from GitHub Secrets. Make sure to configure both.

​
Monitoring Deployments

​
Azure Container Apps

Monitor your Python backend:
  1. Azure Portal: View logs and metrics in Container Apps
  2. Application Insights: Configure for detailed telemetry
  3. GitHub Actions: Check workflow runs for deployment status

​
Vercel

Monitor your Next.js backend:
  1. Vercel Dashboard: View deployment logs and analytics
  2. GitHub Actions: Check workflow status
  3. Vercel CLI: Use vercel logs for real-time logs

​
Rollback Procedures

​
Azure Container Apps

Rollback to a previous image: 
az containerapp update \
  --name tabby-backend \
  --resource-group tabby-rg \
  --image thecubestar/tabby-backend:<previous-commit-sha>

​
Vercel

  1. Go to Deployments in Vercel dashboard
  2. Find the previous successful deployment
  3. Click Promote to Production

​
Troubleshooting

​
Azure Deployment Fails

  • Check Azure credentials are valid and have proper permissions
  • Verify Docker Hub credentials in GitHub Secrets
  • Review workflow logs for specific error messages
  • Ensure resource group and container app exist

​
Vercel Deployment Fails

  • Verify Vercel token is valid
  • Check organization ID and project ID are correct
  • Review build logs in Vercel dashboard
  • Ensure nextjs-backend directory has valid Next.js project

​
Container App Not Starting

  • Check application logs in Azure Portal
  • Verify environment variables are set correctly
  • Test Docker image locally before deploying
  • Ensure port 8000 is exposed and application binds to 0.0.0.0

Build docs developers (and LLMs) love

Get started for freeTalk to us