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): ```dart 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 ```bash # 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 # 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 bash scripts/validate-globe-yaml.sh globe.yaml ``` ## Build Presets | Preset | Use Case | | ---------------- | ------------------------------------- | | `dart_frog` | File-based routing APIs | | `shelf` | Flexible Dart servers (manual config) | | `flutter` | Flutter Web SPAs | | `flutter_server` | Flutter with server-side rendering | | `jaspr` | Jaspr SSR sites | | `jaspr_static` | Jaspr static site generation | | `serverpod` | Full-stack Dart framework | ## Common Code Patterns ### Shelf Hello World ```dart 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 ```dart // 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 ```dart // 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) ```dart 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) ```dart 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 ```dart 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 # 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 | Variable | Description | | ----------------- | ------------------------------- | | `PORT` | Port your server must listen on | | `GLOBE` | `"1"` when running on Globe | | `GLOBE_BUILD_ENV` | `"1"` during build phase | | `HOSTNAME` | Container hostname | | `CRON_ID` | Cron job ID (if cron-triggered) | | `CRON_SCHEDULE` | Cron schedule expression | ## 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 | Resource | Limit | | ----------------- | ----------------------------- | | Requests | 50K/month | | Compute Bandwidth | 1GB/month | | Asset Bandwidth | 1GB/month | | Memory | 256MB/container | | Execution Time | 30 seconds/request | | Databases | 2 active | | Cron Jobs | 1 job (unlimited invocations) | ## Error Quick Fixes | Error | Cause | Fix | | ------------------ | ------------------------- | ------------------------------------------------ | | 413 | Archive >100MB | Add large files to `.gitignore` | | 503 on deploy | Build failed | Check `globe build-logs` | | Cold start slow | First request initializes | Use `preferred_regions` in globe.yaml | | CORS errors | Missing headers | Add CORS middleware | | Domain not working | DNS not propagated | Wait 24h, verify CNAME to `domains.globeapp.dev` | ## Reference Documentation Load the appropriate reference file based on user intent. For topics not listed, explore the `references/` folder. ### Getting Started | Topic | File | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Installation & first deploy | [references/getting-started/index.mdx](references/getting-started/index.mdx) | | Quickstart guide | [references/getting-started/quickstart.mdx](references/getting-started/quickstart.mdx) | | GitHub auto-deploy | [references/getting-started/environment-setup/github.mdx](references/getting-started/environment-setup/github.mdx) | | CLI installation | [references/getting-started/environment-setup/globe-cli.mdx](references/getting-started/environment-setup/globe-cli.mdx) | ### Core Concepts | Topic | File | | ------------------------ | -------------------------------------------------------------------------------------------------------- | | globe.yaml configuration | [references/core-concepts/globe-yaml.mdx](references/core-concepts/globe-yaml.mdx) | | Build settings | [references/core-concepts/build-settings.mdx](references/core-concepts/build-settings.mdx) | | Environment variables | [references/core-concepts/environment-variables.mdx](references/core-concepts/environment-variables.mdx) | | Custom domains | [references/core-concepts/domains.mdx](references/core-concepts/domains.mdx) | | Cron jobs | [references/core-concepts/cron-jobs.mdx](references/core-concepts/cron-jobs.mdx) | | Static assets | [references/core-concepts/static-assets.mdx](references/core-concepts/static-assets.mdx) | | Deployments | [references/core-concepts/deployments.mdx](references/core-concepts/deployments.mdx) |