Your First Deployment

Before You Start

Make sure you have:

• A Staxa account (sign up at the login page)
• A GitHub repository with your application code (or use one of Staxa's templates)
• The Staxa GitHub App installed on your GitHub account (prompted during the wizard if not yet connected)

Step 1: Start the Creation Wizard

Navigate to Tenants → Create New Tenant (or click the "Create a Tenant" quick link from the Help Center).

Enter a tenant name: this becomes part of your subdomain. For example, naming your tenant my-app gives you https://my-app.staxa.dev. Names must be lowercase alphanumeric with hyphens, between 3 and 63 characters.

Step 2: Configure Your Service

A tenant contains one or more services. Your first service is the primary one.

Source type: Choose between GitHub (link a repository) or Container Image (use a pre-built Docker image).

GitHub flow:

• Select a repository from your connected GitHub account
• Choose a branch (defaults to main)
• Staxa automatically detects your framework, runtime version, and default port by analyzing your project files (package.json, requirements.txt, go.mod, Cargo.toml, etc.)
• You can override any detected values

Container Image flow:

• Enter the full image URL (e.g., ghcr.io/your-org/your-app:latest)
• If the image is in a private registry, connect your registry credentials first at Settings → Container Registries

Set the port your application listens on (e.g., 3000 for Node.js, 8000 for Django, 8080 for Go).

Choose a resource size: Small, Medium, or Large. Free and Starter include Small, Growth adds Medium, and Scale includes all three. See Resource Sizes & Health Checks for the exact CPU and memory of each.

Step 3: Database Configuration

Toggle the database on if your app needs one. Choose:

• PostgreSQL (16, 15, 14, or 13), MySQL (8 or 5.7), or Redis (7 or 6)
• A database name (auto-generated from your tenant name)

Staxa provisions the database inside your tenant namespace and auto-injects connection credentials as environment variables. PostgreSQL and MySQL get DATABASE_URL, DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, and DB_NAME; Redis gets REDIS_URL.

Step 4: Environment Variables

Add any environment variables your application needs. You can:

• Add them one-by-one using the key/value editor
• Paste a .env file for bulk import
• Mark variables as secret: they'll be encrypted at rest (AES-256-GCM) and redacted in the UI

Platform variables like DATABASE_URL and STAXA_SERVICE_* URLs are injected automatically, so you don't need to add them manually.

Step 5: Review & Deploy

Review your configuration summary and click Deploy. You'll be redirected to the tenant detail page where you can watch the deployment progress in real-time:

1. Cloning repository
2. Building container image
3. Pushing to internal registry
4. Creating namespace and resources
5. Provisioning database
6. Starting application
7. Configuring networking and SSL
8. Health check passing → Ready

Once the status shows "ready," click the deployment URL to open your running application.

Troubleshooting

• Build fails: Check that your Dockerfile or auto-detected framework configuration is correct. Review build logs on the tenant detail page under the service's deployment history.
• Health check fails: Ensure your app listens on the port you specified and that the health check path returns a 2xx or 3xx response. You can change the path, switch to a TCP check, or turn the check off for workers that never listen on a port.
• Missing environment variables: Go to the Shared Env tab on the tenant detail page to verify all required variables are set. Redeploy after adding missing variables.
• Image pull errors: If using a private registry image, verify your registry credentials at Settings → Container Registries and ensure the credential is verified.