Backend Deployment - Tabby AI Keyboard

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

Platform: Azure Container Apps
Workflow: .github/workflows/backend-deploy.yml
Container Registry: Docker Hub (thecubestar/tabby-backend)
Production URL: tabby-backend.jollydesert-22a4756c.centralindia.azurecontainerapps.io
Trigger: Push to backend/ directory on main branch

Prerequisites

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.

Set up GitHub Secrets

Add these secrets to your GitHub repository (Settings → Secrets and variables → Actions):

Secret Name	Description
`DOCKER_USERNAME`	Your Docker Hub username
`DOCKER_PASSWORD`	Your Docker Hub password or access token
`AZURE_CREDENTIALS`	Azure 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:

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

Push to Docker Hub

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

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:

Build Docker image locally

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

Push to Docker Hub

docker push thecubestar/tabby-backend:manual

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

Create Vercel project

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

Generate Vercel token

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

Configure GitHub Secrets

Add these secrets to your repository:

Secret Name	Description
`VERCEL_TOKEN`	Your Vercel authentication token
`ORG_ID`	Your Vercel organization ID
`PROJECT_ID`	Your Vercel project ID
`GH_TOKEN`	GitHub 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:

Checkout code

- uses: actions/checkout@v4

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:

Go to your project Settings → Environment Variables
Add required variables for your Next.js backend
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:

Azure Portal: View logs and metrics in Container Apps
Application Insights: Configure for detailed telemetry
GitHub Actions: Check workflow runs for deployment status

Vercel

Monitor your Next.js backend:

Vercel Dashboard: View deployment logs and analytics
GitHub Actions: Check workflow status
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

Go to Deployments in Vercel dashboard
Find the previous successful deployment
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

​Python Backend (Azure Container Apps)

​Deployment Overview

​Prerequisites

​Docker Configuration

​Deployment Workflow

​Environment Variables

​Manual Deployment

​Next.js Backend (Vercel)

​Deployment Overview

​Prerequisites

​Deployment Workflow

​Environment Variables in Vercel

​Monitoring Deployments

​Azure Container Apps

​Vercel

​Rollback Procedures

​Azure Container Apps

​Vercel

​Troubleshooting

​Azure Deployment Fails

​Vercel Deployment Fails

​Container App Not Starting

Python Backend (Azure Container Apps)

Deployment Overview

Prerequisites

Docker Configuration

Deployment Workflow

Environment Variables

Manual Deployment

Next.js Backend (Vercel)

Deployment Overview

Prerequisites

Deployment Workflow

Environment Variables in Vercel

Monitoring Deployments

Azure Container Apps

Vercel

Rollback Procedures

Azure Container Apps

Vercel

Troubleshooting

Azure Deployment Fails

Vercel Deployment Fails

Container App Not Starting