Deployment

Maravilla offers multiple ways to deploy your applications, from simple manual uploads to fully automated CI/CD pipelines. All deployments are atomic, immutable, and distributed globally with zero downtime.

Deployment Methods

1. Git Push Deployment

Push code to a Maravilla-hosted git remote and your site is built and deployed automatically. This is the recommended workflow for most projects.

# Add the Maravilla remote to your project
git remote add maravilla http://<tenant>.git.maravilla.cloud/<namespace>/<project>.git

# Push to deploy
git push maravilla main

When you push:

1. The receive-pack hook detects the push event
2. If .maravilla/pipeline.yml exists, the full pipeline runs (test, lint, build, etc.)
3. If no pipeline file exists, Maravilla runs a single build job: clone, detect framework, install dependencies, build, and deploy
4. The build artifact is extracted to the deployment directory
5. Your site is live at https://<project>-<handle>.maravilla.page

2. Pipeline Deployment

For projects with a .maravilla/pipeline.yml, deployment is triggered automatically when the pipeline completes. The pipeline produces build artifacts, and Maravilla deploys them directly — no re-build happens on the deployment side.

# .maravilla/pipeline.yml
name: build-and-deploy
image: node:22-alpine

on:
  push:
    branches: [main]

jobs:
  install:
    commands:
      - npm ci
    artifacts:
      paths: [node_modules/]

  test:
    needs: install
    commands:
      - npm test

  build:
    needs: [install, test]
    commands:
      - npm run build
    artifacts:
      paths: [dist/]

The build job’s dist/ artifact is collected and deployed automatically. See the Pipelines documentation for the full YAML reference.

3. ZIP Upload via Web UI

Upload a ZIP file containing your static site through the Maravilla dashboard. Best for quick updates and one-off deployments.

1. Navigate to your project dashboard
2. Click Deploy or drag and drop a ZIP file
3. The archive is extracted and deployed immediately

File limits:

• Individual file: 50 MB
• Total deployment: 250 MB

4. API Key Deployment

Deploy programmatically using project-scoped API keys. This integrates with any CI/CD system.

# Upload a ZIP file with an API key
curl -X POST https://api.maravilla.cloud/api/upload \
  -H "X-API-Key: your-project-api-key" \
  -F "file=@dist.zip"

Generate an API key in your project settings under Settings > API Keys. Each key is scoped to a single project.

API keys work with any CI/CD provider:

# GitHub Actions example
- name: Deploy to Maravilla
  run: |
    zip -r dist.zip dist/
    curl -X POST https://api.maravilla.cloud/api/upload \
      -H "X-API-Key: ${{ secrets.MARAVILLA_API_KEY }}" \
      -F "file=@dist.zip"

Deployment Process

1. Upload Phase

Your files are uploaded to Maravilla’s processing servers:

• ZIP extraction (for uploads)
• Git clone (for push deployments)
• File validation

2. Build Phase

If build settings are configured (or auto-detected):

• Framework detection (40+ frameworks supported)
• Dependency installation (npm ci, yarn install, bundle install, etc.)
• Build command execution
• Output collection

Maravilla auto-detects frameworks like Astro, Next.js, Gatsby, Hugo, Jekyll, Vite, SvelteKit, and many more. You can override detection with manual build settings.

3. Deploy Phase

Files are distributed to the hosting infrastructure:

• Atomic switch to new version
• Zero downtime
• Subdomain routing via https://<project>-<handle>.maravilla.page

Custom Domains and SSL

Custom domains are supported with automatic SSL certificate provisioning:

1. Add your custom domain in Settings > Domains
2. Configure DNS to point to your Maravilla deployment:
   • CNAME record: yourdomain.com -> <project>-<handle>.maravilla.page
   • Or an A record pointing to the provided IP address
3. SSL certificates are automatically provisioned and renewed via Let’s Encrypt

Environment Variables and Secrets

Maravilla provides a secure Vault for storing environment variables, API keys, and sensitive configuration.

Setting Variables

1. Navigate to your project dashboard
2. Go to Settings > Vault
3. Click Add Entry and provide a key-value pair

Key: STRIPE_API_KEY
Value: sk_live_xxxxxxxxxxxxxx
Description: Production Stripe API key

How Variables Are Used

• Variables are injected at build time as environment variables
• Your build commands (e.g., npm run build) have full access to them
• Variables are encrypted at rest with AES-256-GCM
• They never appear in deployed files or API responses

Framework Prefixes

Follow your framework’s conventions for client-side variables:

Pipeline Secrets

For CI/CD pipelines, secrets are managed separately via the pipeline secret store:

# Set a pipeline secret via API
POST /api/v1/repos/{ns}/{repo}/pipelines/secrets

Secrets declared in your pipeline.yml are injected into pipeline jobs:

secrets: [DATABASE_URL, DEPLOY_TOKEN]

Deployment Rollback

Every deployment is immutable and tracked. Roll back to any previous deployment:

1. Navigate to your project’s Deployments tab
2. Find the deployment you want to revert to
3. Click Rollback

Rollback is instant — the previous version is activated without a rebuild. Your site switches atomically with zero downtime.

Deployment States

Storage Modes

Maravilla supports two storage modes:

Local Mode (Default)

Build artifacts are stored on the local filesystem. Best for single-server and bare-metal deployments.

Cloud Storage Mode

Build artifacts are uploaded to cloud object storage. Best for multi-region setups with CDN distribution.

Best Practices

1. Test locally before deploying — run maravilla build and maravilla preview to verify your production build
2. Use pipelines for team projects — add tests and linting as gates before deployment
3. Store secrets in the Vault — never commit API keys or credentials to your repository
4. Use framework auto-detection — Maravilla handles build commands and output directories automatically for 40+ frameworks
5. Tag releases — use git tags to mark deployments for easy rollback identification