Deploying To Globe

Globe Deployment Skill

Globe is a serverless deployment platform for Dart and Flutter applications. Apps compile to x86_64 native executables and deploy to 300+ edge locations with automatic scaling.

Critical Requirements

All Globe server apps MUST:

1. Listen on PORT environment variable (not hardcoded):

final port = int.parse(Platform.environment['PORT'] ?? '8080');

2. Be stateless — no local file persistence between requests

3. Compile FFI to x86_64 if using native code

CLI Quick Reference

# Install
dart pub global activate globe_cli

# Auth
globe login
globe logout

# Project Management
globe link              # Link existing project
globe unlink            # Unlink project
globe create -t <tpl>   # New project from template

# Deploy
globe deploy            # Preview deployment
globe deploy --prod     # Production deployment
globe build-logs        # Stream build logs

# Tokens (for CI/CD)
globe token create
globe token list
globe token delete

Global flags: --help, --verbose, --token <t>, --project <id>, --org <id>

globe.yaml (Optional)

Globe auto-detects most project types. A globe.yaml is required for:

• Cron jobs — must be defined in config file
• Static assets — must be defined in config file

Other settings (preferred regions, build settings, etc.) can be configured via the dashboard instead.

Example (when needed):

# yaml-language-server: $schema=https://globe.dev/globe.schema.json

entrypoint: bin/server.dart

build:
  preset:
    type: dart_frog # or: shelf, flutter, jaspr, serverpod

# These require globe.yaml:
assets:
  - public/

crons:
  - id: daily_cleanup
    schedule: "0 0 * * *"
    path: "/cron/cleanup"

Validate (if globe.yaml exists):

bash scripts/validate-globe-yaml.sh globe.yaml

Build Presets

Common Code Patterns

Shelf Hello World

import 'dart:io';
import 'package:shelf/shelf.dart';
import 'package:shelf/shelf_io.dart' as io;

void main() async {
  final port = int.parse(Platform.environment['PORT'] ?? '8080');
  final handler = const Pipeline()
      .addMiddleware(logRequests())
      .addHandler((req) => Response.ok('Hello from Globe!'));
  await io.serve(handler, InternetAddress.anyIPv4, port);
}

Environment Variables

// User-defined secrets (set in Globe dashboard)
final apiKey = Platform.environment['API_KEY'];
final dbUrl = Platform.environment['DATABASE_URL'];

// Globe system variables (auto-set)
final isGlobe = Platform.environment['GLOBE'] == '1';
final buildEnv = Platform.environment['GLOBE_BUILD_ENV']; // 'preview' or 'production'

Cron Job Handler

// Cron jobs POST to your path at scheduled times
app.post('/cron/daily', (Request req) async {
  final cronId = req.headers['x-globe-cron-id'];
  // Do work...
  return Response.ok('done'); // 2xx = success
});

Globe KV (Key-Value Store)

import 'package:globe_kv/globe_kv.dart';

final kv = GlobeKV('namespace-id'); // Create namespace in dashboard first

await kv.set('key', 'value', ttl: 3600);  // TTL in seconds
final value = await kv.getString('key');
await kv.delete('key');
final keys = await kv.list(prefix: 'user:', limit: 100);

Globe DB (SQLite)

import 'package:drift/drift.dart';
import 'package:drift/native.dart';
import 'package:sqlite3/sqlite3.dart';

// Connect to Globe DB (name from dashboard)
final db = NativeDatabase.opened(sqlite3.open('your-db-name.db'));

Globe AI

import 'package:globe_ai/globe_ai.dart';

final result = await generateText(
  model: openai.chat('gpt-4o'),
  prompt: 'What is the capital of France?',
);

globe.yaml Full Example

# yaml-language-server: $schema=https://globe.dev/globe.schema.json

entrypoint: bin/server.dart

build:
  preset:
    type: dart_frog
    version: "2.0.0" # Optional: pin framework version
    buildCommand: "custom" # Optional: override build command
  build_runner:
    automatic_detection: true
    command: "dart run build_runner build" # Optional override
  melos:
    automatic_detection: true # For monorepos
    command: "melos bootstrap"
    version: "3.0.0"

assets:
  - public/
  - assets/images/

crons:
  - id: daily_cleanup # 1-50 chars, alphanumeric + underscores
    schedule: "0 0 * * *" # Cron expression (midnight UTC)
    path: "/cron/cleanup"

preferred_regions: # See full list below
  - us-east1
  - europe-west1

Preferred Regions

Valid values for preferred_regions:

africa-south1, asia-east1, asia-east2, asia-northeast1, asia-northeast2,
asia-northeast3, asia-south1, asia-south2, asia-southeast1, asia-southeast2,
australia-southeast1, australia-southeast2, europe-central2, europe-north1,
europe-southwest1, europe-west1, europe-west2, europe-west3, europe-west4,
europe-west6, europe-west8, europe-west9, europe-west10, europe-west12,
me-central1, me-central2, me-west1, northamerica-northeast1, northamerica-northeast2,
northamerica-south1, southamerica-east1, southamerica-west1, us-central1,
us-east1, us-east4, us-east5, us-south1, us-west1, us-west2, us-west4

System Environment Variables

Globe Request Headers

Globe adds these headers to incoming requests:

• x-globe-country — ISO country code
• x-globe-city — City name
• x-globe-region — Region/state
• x-globe-latitude / x-globe-longitude — Coordinates
• x-globe-timezone — IANA timezone
• x-globe-temperature — cold, warm, or hot (container state)

Resource Limits

Error Quick Fixes

Reference Documentation

Load the appropriate reference file based on user intent. For topics not listed, explore the references/ folder.

Getting Started

Core Concepts

CLI Commands

Frameworks

Products

Infrastructure

Guides

Tutorials

Troubleshooting

Deployment Workflow

Copy this checklist and track progress:

Deployment Progress:
- [ ] Step 1: Verify PORT usage in code
- [ ] Step 2: Create globe.yaml (only if needed for crons/assets/regions)
- [ ] Step 3: Set environment variables in dashboard (if needed)
- [ ] Step 4: Run `globe deploy` for preview
- [ ] Step 5: Test preview URL
- [ ] Step 6: Run `globe deploy --prod` for production
- [ ] Step 7: Configure custom domain (if needed)

Step 1: Ensure server listens on Platform.environment['PORT']

Step 2: Create globe.yaml only if you need cron jobs or static assets. Globe auto-detects presets for most projects.

Step 3: Add secrets via Dashboard → Settings → Environment Variables

Step 4: Deploy preview: globe deploy

Step 5: Test the preview URL thoroughly

Step 6: Deploy production: globe deploy --prod

Step 7: Add custom domain via Dashboard → Domains → CNAME to domains.globeapp.dev

Decision Tree

Deploying Dart/Flutter to Globe?
├── New project?
│   ├── Yes → globe create -t <template>
│   └── No → globe link
│
├── Framework?
│   ├── Dart Frog → preset: dart_frog (auto-detected)
│   ├── Shelf → preset: shelf
│   ├── Flutter Web → preset: flutter
│   └── Jaspr → preset: jaspr
│
├── Deployment type?
│   ├── Preview → globe deploy
│   └── Production → globe deploy --prod
│
├── Needs caching?
│   └── Globe KV → Create namespace in dashboard, use globe_kv package
│
├── Needs database?
│   └── Globe DB → Create in dashboard, use Drift with sqlite3
│
├── Needs AI?
│   └── Globe AI → Install globe_ai, configure model provider
│
├── Background jobs?
│   └── Add crons to globe.yaml, handler returns 2xx
│
├── Custom domain?
│   └── Dashboard → Domains → Add → CNAME to domains.globeapp.dev
│
└── CI/CD?
    ├── GitHub → Enable GitHub integration
    └── Other → globe token create