diff --git a/docs.yaml b/docs.yaml new file mode 100644 index 00000000..7e5b7b54 --- /dev/null +++ b/docs.yaml @@ -0,0 +1,64 @@ +--- +name: Docs +logo: "/assets/globe_dark.png" +logoDark: "/assets/globe_light.png" +twitter: dart_globe +anchors: +- title: Discord + icon: discord + link: https://invertase.link/globe-discord +theme: "#FFA03F" +favicon: "/assets/globe_dark.png" +sidebar: +- - Overview + - "/" +- - Getting Started + - "/getting-started" +- - CLI + - - - CLI Overview + - "/cli" + - - Deploy + - "/cli.commands.deploy" + - - Link + - "/cli.commands.link" + - - Login + - "/cli.commands.login" + - - Logout + - "/cli.commands.logout" + - - Unlink + - "/cli.commands.unlink" +- - Deployments + - - - Overview + - "/deployments" + - - Build Settings + - "/deployments.build-settings" + - - Domains + - "/deployments.domains" + - - Environment Variables + - "/deployments.environment-variables" + - - GitHub Integration + - "/deployments.github-integration" + - - Hooks + - "/deployments.hooks" + - - Redeployments + - "/deployments.redeployments" +- - Frameworks + - - - Overview + - "/frameworks" + - - Dart Frog + - "/frameworks.dart-frog" + - - Jaspr + - "/frameworks.jaspr" +- - Infrastructure + - - - Overview + - "/infrastructure" + - - Cold Starts + - "/infrastructure.cold-starts" + - - Cron Jobs + - "/infrastructure.cron-jobs" + - - Headers + - "/infrastructure.headers" + - - Regions + - "/infrastructure.regions" + - - WebSockets + - "/infrastructure.websockets" \ No newline at end of file diff --git a/docs/assets/globe_dark.png b/docs/assets/globe_dark.png new file mode 100644 index 00000000..f86a4b77 Binary files /dev/null and b/docs/assets/globe_dark.png differ diff --git a/docs/assets/globe_light.png b/docs/assets/globe_light.png new file mode 100644 index 00000000..c9f7db30 Binary files /dev/null and b/docs/assets/globe_light.png differ diff --git a/docs/cli.commands.deploy.mdx b/docs/cli.commands.deploy.mdx new file mode 100644 index 00000000..b85c235a --- /dev/null +++ b/docs/cli.commands.deploy.mdx @@ -0,0 +1,37 @@ +--- +title: Deploy a project with the Globe CLI +description: Deploy your Dart application to Globe directly from the command line. +--- + +# Deploy + +The `deploy` command allows you to deploy your Dart application to Globe directly from the command line. + +If you have not yet [linked a project](/docs/cli/commands/link), you will be prompted to do so before deploying. + +### Usage + +To deploy a project, run the following command from your Dart project root directory. + +```bash +globe deploy +``` + +The CLI will upload your project to Globe and trigger a new deployment. Upon success, you will provided a URL to view deployment progress on the Globe dashboard. + +By default, deployments via the `deploy` command are treated as a preview deployment. This means that once deployed, the deployment will have it's own unique URL generated by Globe. +To deploy as a production deployment, append the `--prod` flag to the command. + +```bash +globe deploy --prod +``` + +When successfully built, the deployment will be promoted to production and will be accessible via the project's primary domain(s). + +You can learn more about [preview and production deployments](/docs/deployments) in the deployments documentation. + +### Flags + +The command has flags (in addition to [global flags](/docs/cli)) that can be used to modify the behavior of the command, which can be accessed by running `globe deploy --`: + +- `--prod` - Creates a deployment which will be promoted to production once built. diff --git a/docs/cli.commands.link.mdx b/docs/cli.commands.link.mdx new file mode 100644 index 00000000..945f9d65 --- /dev/null +++ b/docs/cli.commands.link.mdx @@ -0,0 +1,29 @@ +--- +title: Link a project to Globe +--- + +# Link + +The `link` command links a local Dart project to a Globe project. Linking is required to deploy a project to Globe. + +Project linking is carried out automatically if the project is not yet linked when running the [`deploy`](/docs/cli/commands/deploy) command. + +## Usage + +```bash +globe link +``` + +The `link` command will first prompt, asking whether you wish to continue linking the local project. If you continue, you will be further prompted to: + +1. Select an account you wish to link this project to. +2. Select, or create a new project to link this project to. + +Upon completion, the project will be linked to your Globe account and you will be able to deploy the project. + +## Details + +A linked project stores metadata about the project in the local `.dart_tool/dart_globe` directory on your machine. This metadata is used to identify the project when deploying to Globe. If not already, +the `.dart_tool` directory should not be committed to your Git repository. You can add this directory to your `.gitignore` file to ensure it is not committed. + +If you accidentally delete this directory, or run the [`unlink`](/docs/cli/commands/unlink) command, you will need to re-link the project before you can deploy again. diff --git a/docs/cli.commands.login.mdx b/docs/cli.commands.login.mdx new file mode 100644 index 00000000..1c9213a2 --- /dev/null +++ b/docs/cli.commands.login.mdx @@ -0,0 +1,22 @@ +--- +title: Login to Globe +--- + +# Login + +The `login` command allows you to authenticate your local CLI with your Globe account. This is required before you can deploy any projects. + +## Usage + +```bash +globe login +``` + +A new browser window will open prompting you to login to your Globe account. Once you have logged in, you will be redirected to a page notifying you of a successful login. You can close this page once complete. +Globe will store a secure token on your local machine to authenticate future requests. + +If you wish to [logout](/docs/cli/commands/logout), you can run the following command: + +```bash +globe logout +``` diff --git a/docs/cli.commands.logout.mdx b/docs/cli.commands.logout.mdx new file mode 100644 index 00000000..452bd1f4 --- /dev/null +++ b/docs/cli.commands.logout.mdx @@ -0,0 +1,15 @@ +--- +title: Logout of Globe +--- + +# Logout + +The `logout` command allows removes any prior authentication tokens from your local machine. Once you have logged out, you will need to login again before you can deploy any projects. + +## Usage + +```bash +globe logout +``` + +A message will be displayed notifying you that you have been logged out. diff --git a/docs/cli.commands.unlink.mdx b/docs/cli.commands.unlink.mdx new file mode 100644 index 00000000..149b2b16 --- /dev/null +++ b/docs/cli.commands.unlink.mdx @@ -0,0 +1,17 @@ +--- +title: Unlink a project from Globe +--- + +# Unlink + +The `unlink` command removes any previously linked projects from the current local project. This will prevent you from deploying the project to Globe. + +## Usage + +```bash +globe unlink +``` + +## Details + +The command removes the `.dart_tool/dart_globe` directory from the local project. This directory stores metadata about the project, which is used to identify the project when deploying to Globe. diff --git a/docs/cli.mdx b/docs/cli.mdx new file mode 100644 index 00000000..05a84444 --- /dev/null +++ b/docs/cli.mdx @@ -0,0 +1,45 @@ +--- +title: Globe CLI +description: Install and start deploying using the Globe CLI. +--- + +# Globe CLI + +The Globe CLI is a command line tool that helps you deploy and interact with your Dart applications via Globe. + +## Pre-requisites + +To get started, you must have the [Dart SDK](https://dart.dev/get-dart) installed on your machine. + +## Installation + +To install the Globe CLI, run the following command: + +```bash +dart pub global activate globe_cli +``` + +Once installed, you can access the `globe` executable from anywhere on your machine. + +To login with your Globe account, run the following command: + +```bash +globe login +``` + +## Commands + +The Globe CLI provides the following commands, which can be accessed by running `globe `: + +- [`deploy`](/cli/commands/deploy) - Deploy your Dart application to Globe directly from the command line. +- [`link`](/cli/commands/link) - Link a local project to a Globe project. +- [`login`](/cli/commands/login) - Login to your Globe account. +- [`logout`](/cli/commands/logout) - Logout of your Globe account. +- [`unlink`](/cli/commands/unlink) - Unlink a local project from a Globe project. + +## Global Flags + +All CLI commands have global flags that can be used to modify the behavior of the command, which can be accessed by running `globe --`. + +- `--help` - Display help information for the command. +- `--verbose` - Display verbose output for the command, such as API calls and debug information. diff --git a/docs/deployments.build-settings.mdx b/docs/deployments.build-settings.mdx new file mode 100644 index 00000000..7e9bab14 --- /dev/null +++ b/docs/deployments.build-settings.mdx @@ -0,0 +1,60 @@ +--- +title: Build Settings +--- + +# Build Settings + +Build settings allow you to configure how your project is build during a new deployment. You can configure your build settings via the dashboard: **Project** -> **Settings** -> **General**. + +![Project Settings](/docs/project-settings.png) + +## Settings + +You can configure the following build settings: + +- [Dart Version](#dart-version) +- [Root Directory](#root-directory) +- [Framework Preset](#framework-preset) +- [Build Command](#build-command) +- [Entrypoint](#entrypoint) + +--- + +### Dart Version + +The Dart version to use when building your project. By default, Globe will use the latest stable version of Dart. Currently Dart supports `stable` and `beta` version branches. + +Support for specific tagged versions is coming soon. + +--- + +### Root Directory + +The root directory is the directory which contains your project source. If working with mono-repositories of a directory structure where your application is not at the root where the `pubspec.yaml` file exists. + +--- + +### Framework Preset + +Globe supports existing [frameworks](/docs/frameworks). If a framework is specified here, Globe will use default values required to build and deploy your framework application. If you'd like to override these values, you can do so by specifying a value in the specific build settings. + +--- + +### Build Command + +A build command can be executed after project dependencies have been installed. This is useful if you need to run a build step before your application can be deployed. + +If using a **Framework Preset**, a default value will be used instead. You can override this by specifying a value here. + +--- + +### Entrypoint + +When building your application, the build system requires an entrypoint file which is used to bootstrap your application. The is typically the `lib/main.dart` file in your project +which contains a `main` function. + +This setting can be configured if your application uses a different entrypoint file. + +If using a **Framework Preset**, a default value will be used instead. You can override this by specifying a value here. + +--- diff --git a/docs/deployments.domains.mdx b/docs/deployments.domains.mdx new file mode 100644 index 00000000..fd69f7f2 --- /dev/null +++ b/docs/deployments.domains.mdx @@ -0,0 +1,17 @@ +--- +title: Domains +--- + +# Domains + +A domain is the address of your deployment. + +Each deployment, production or preview gets assigned a unique domain which directly points to the specific deployment. If the deployment is not yet ready or successful, visiting a domain will redirect you to the dashboard for that deployment. + +## Production domains + +Each project gets assigned a unique domain when it is created. Whenever you successfully deploy to the production environment, the production domain will be updated to point to the latest deployment. + +### Custom Domains + +Custom domains are not yet supported. We are working on it. diff --git a/docs/deployments.environment-variables.mdx b/docs/deployments.environment-variables.mdx new file mode 100644 index 00000000..435fab37 --- /dev/null +++ b/docs/deployments.environment-variables.mdx @@ -0,0 +1,34 @@ +--- +title: Environment Variables +--- + +# Environment Variables + +Environment variables are a set of named values that can affect the way running processes will behave on a deployment. An environment variable can be used to store secret values which are not safe to be stored in the codebase. You may wish to use +different values for different environments, such as development, preview, and production to connect to different databases or API endpoints. + +## Creating environment variables + +To create a new environment variable, navigate to the **Environment Variables** tab in the **Settings** section of the project on the dashboard. Click the **Add Variable** button. + +![New Environment Variable](/docs/new-env-variable.png) + +Enter the name and value of your variable. All values are encrypted, and can only be viewed by a specifically viewing it on the dashboard. + +It is also possible to specify what environments the variable should be available in. + +## Accessing environment variables + +Within your Dart code, you can access environment variables using the `Platform.environment` map. + +```dart +String? value = Platform.environment['MY_VARIABLE']; +``` + +## System environment variables + +The following environment variables are available on all deployments: + +| Name | Description | +| ------ | ----------------------------------------------- | +| `PORT` | The port that the application should listen on. | diff --git a/docs/deployments.github-integration.mdx b/docs/deployments.github-integration.mdx new file mode 100644 index 00000000..4e506e4f --- /dev/null +++ b/docs/deployments.github-integration.mdx @@ -0,0 +1,22 @@ +--- +title: GitHub Integration +--- + +# GitHub Integration + +Globe integrates with GitHub via the [GitHub Application](https://github.com/apps/dart-globe). + +## Features + +- Import a new project from GitHub, specifying the repository, root directory and branch of your Dart project. +- Create new deployments when you push to GitHub. +- Trigger production builds whenever you push to a specified production branch. +- Show deployment status on each commit. + +## Authorization + +TODO: Add authorization instructions. + +## Configuration + +TODO: Add configuration instructions. diff --git a/docs/deployments.hooks.mdx b/docs/deployments.hooks.mdx new file mode 100644 index 00000000..4bfd01dc --- /dev/null +++ b/docs/deployments.hooks.mdx @@ -0,0 +1,10 @@ +--- +title: Deployment Hooks +--- + +# Deployment Hooks + +Deployment hooks allow you to provide a webhook endpoint which will be called throughout the lifecycle of a deployment, for example +when a deployment is created, built, or deployed. + +Deployment hooks are an in development feature and will be available soon. diff --git a/docs/deployments.mdx b/docs/deployments.mdx new file mode 100644 index 00000000..d1b119a8 --- /dev/null +++ b/docs/deployments.mdx @@ -0,0 +1,51 @@ +--- +title: Deploying to Globe +--- + +# Deployments + +A deployment can be triggered when you wish to deploy new code to your Globe project. In Globe, a deployment can be staged to two environments; **Production** or **Preview**. +When a Production deployment has successfully built, your domains will be updated automatically to point to the new deployment. Preview deployments on the other are accessible +via a URL unique to the deployment. This allows you to test and share your changes on a live environment before deploying to production. + +![Deployments](/docs/deployments.png) + +Once deployments have successfully built, you can access the unique URL from the Globe dashboard. + +## Creating a preview deployment + +To create a new preview deployment, you have two options: + +### via the CLI + +Run the [`deploy`](/docs/cli/commands/deploy) command. By default, deployments from the CLI are staged as a preview deployment: + +```bash +globe deploy +``` + +### via GitHub + +Using the [GitHub Integration](/docs/deployments/github-integration), you can trigger a preview deployment by pushing to a branch which +is not defined as the production branch in your projects settings. + +To learn more, view the [GitHub Integration](/docs/deployments/github-integration) documentation. + +## Creating a production deployment + +To create a new production deployment, you have two options: + +### via the CLI + +Run the [`deploy`](/docs/cli/commands/deploy) command with the `--prod` flag: + +```bash +globe deploy --prod +``` + +### via GitHub + +Using the [GitHub Integration](/docs/deployments/github-integration), you can trigger a production deployment by pushing to the branch +specified in your projects settings. By default, this is the `main` branch. + +To learn more, view the [GitHub Integration](/docs/deployments/github-integration) documentation. diff --git a/docs/deployments.redeployments.mdx b/docs/deployments.redeployments.mdx new file mode 100644 index 00000000..62d48027 --- /dev/null +++ b/docs/deployments.redeployments.mdx @@ -0,0 +1,19 @@ +--- +title: Redeployments +--- + +# Redeployments + +Redeployments are the process of triggering a new deployment build from a previous deployment. This is useful if you update build settings or environment variables and want to apply those changes without making any other changes to your code. + +Redeployments apply any new build settings and environment variables you might have updated since the original deployment. + +## Redeploying from the Dashboard + +To redeploy from the dashboard, click the **Redeploy** button on the deployment you want to redeploy: + +![Redeployments](/docs/redeploy.png) + +## Redeploying other redeployments + +When redeploying a redeployment, the original deployment will be used as the base for the new deployment. diff --git a/docs/frameworks.dart-frog.mdx b/docs/frameworks.dart-frog.mdx new file mode 100644 index 00000000..381db969 --- /dev/null +++ b/docs/frameworks.dart-frog.mdx @@ -0,0 +1,27 @@ +--- +title: Deploying a Dart Frog application +--- + +# Deploying a Dart Frog application + +[Dart Frog](https://dartfrog.vgv.dev/) is a fast, minimalistic backend framework for Dart which is built on top of [Shelf](https://pub.dev/packages/shelf). Dart Frog supports routing, middleware, and DI out of the box with a local CLI to assist with development. + +Follow their [documentation](https://dartfrog.vgv.dev/docs/overview) for assistance with installing the CLI. + +## Create a new project + +Create a new Dart Frog project by running the following command: + +```bash +dart_frog create my_dart_frog_app +``` + +Start a local development server with the following command: + +```bash +dart_frog dev +``` + +## Deploying to Globe + +Deploying your project through the CLI or the dashboard will work as normal. Globe will detect Dart Frog is being used and automatically select it as a framework preset on your project settings. No additional steps are required. diff --git a/docs/frameworks.jaspr.mdx b/docs/frameworks.jaspr.mdx new file mode 100644 index 00000000..a41c62a2 --- /dev/null +++ b/docs/frameworks.jaspr.mdx @@ -0,0 +1,34 @@ +--- +title: Deploying a Jaspr application +--- + +# Deploying a Dart Frog application + +[Jaspr](https://pub.dev/packages/jaspr) is a modern web framework for building websites in Dart with support for both client-side and server-side rendering. + +Follow the [documentation](https://pub.dev/packages/jaspr#get-started) for assistance with installing the Jaspr CLI. + +## Create a new project + +Create a new Dart Frog project by running the following command: + +```bash +jaspr create my_jaspr_app +``` + +Start a local development server with the following command: + +```bash +dart run jaspr serve +``` + +## Deploying to Globe + +Before deploying your application to Globe, ensure you have the Server Side Rendering disabled flag disabled in your `pubspec.yaml` file: + +```yaml +jaspr: + uses-ssr: false +``` + +This will enable Globe to build and serve your application instead. Globe will detect Jaspr is being used and automatically select it as a framework preset on your project settings. No additional steps are required. diff --git a/docs/frameworks.mdx b/docs/frameworks.mdx new file mode 100644 index 00000000..301ccc1b --- /dev/null +++ b/docs/frameworks.mdx @@ -0,0 +1,14 @@ +--- +title: Frameworks +--- + +# Frameworks + +Globe aims to be framework agnostic, however, some frameworks have additional steps like build commands that need to be ran before deployment. Globe supports these frameworks by automatically providing default build settings for each framework that can used to build and deploy your application. + +## Supported Frameworks + +On-going work is being done to support more frameworks. If you'd like to see a framework supported please submit a [feature request](https://invertase.canny.io/globe). + +- [Dart Frog](/docs/frameworks/dart-frog) +- [Jaspr](/docs/frameworks/jaspr) diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx new file mode 100644 index 00000000..c1497b9b --- /dev/null +++ b/docs/getting-started.mdx @@ -0,0 +1,97 @@ +--- +title: Getting started with Globe +--- + +# Getting Started + +To get started using Globe, ensure you have [logged in](/login) to your account and have access. Globe is current in private alpha, so only select users have access. + +## Install the Globe CLI (optional) + +The Globe CLI is a command line tool that allows you to interact with your Globe account and deploy from the command line. It is not required to use Globe, but it can be useful for some workflows. + +To install the Globe CLI, run the following command: + +```bash +dart pub global activate globe_cli +``` + +Once installed, you can access the globe executable from anywhere on your machine. + +To login with your Globe account, run the following command: + +```bash +globe login +``` + +To learn more about the CLI, view the [documentation](/docs/cli). + +## Create a new Dart project + +To get started with, we're going to create a simple Dart application which will be deployed to Globe. We'll use [Shelf](https://pub.dev/packages/shelf) to start a HTTP server which can handle requests and log some information about our application. Let's go ahead and create a basic Dart application. In your terminal, run the following command where you'd like to create a project: + +```bash +dart create my_shelf_app +``` + +Rename the file `lib/my_shelf_app.dart` to `lib/main.dart` - this is the entrypoint for our application. Next, install the [`shelf`](https://pub.dev/packages/shelf) package via pub: + +```bash +dart pub add shelf +``` + +Copy the following code into `lib/main.dart`: + +```dart +import 'dart:io'; + +import 'package:shelf/shelf.dart'; +import 'package:shelf/shelf_io.dart' as shelf_io; + +void main() async { + final handler = + const Pipeline().addMiddleware(logRequests()).addHandler(_echoRequest); + + final server = await shelf_io.serve( + handler, + InternetAddress.anyIPv4, + int.tryParse(Platform.environment['PORT'] ?? '8080') ?? 8080, + ); + + print('Serving at http://${server.address.host}:${server.port}'); +} + +Response _echoRequest(Request request) => + Response.ok('Request for "${request.url}"... worked!'); +``` + +To test your application out locally, run `dart run lib/main.dart` and visit `http://0.0.0.0:8080/hello` in your browser. You should see the following: `Request for "hello"... worked!`. + +This is a basic HTTP server that will respond to any request with a 200 OK response and the body `Request for "${request.url}"... worked!`, whilst also logging out information about the request. From here you could build out a full application yourself, adding in routing, database calls, middleware and more. For this example, we'll keep it simple. + +## Deploying to Globe + +Now that we have a basic application, we can deploy it to Globe. Deploying to Globe is simple; run the `globe deploy` command from your project root in the terminal: + +```bash +globe deploy +``` + +The first time you deploy, you'll: + +1. Be prompted to continue with setup of the deployment (press `Y`) +1. Enter a name for your project: Enter: `my-shelf-app` + +After waiting for a couple of seconds, you'll be shown that your new deployment has been queued and be provided a unique URL for that deployment. You can visit this URL in your browser to view the build logs and deployment status. + +## Viewing your deployment logs + +Once complete, your deployment will be available via the URL shown in the dashboard. Each deployment has it's own unique URL, with a `globeapp.dev` domain. Click the URL and you'll be shown the `Request for "hello"... worked!` message which your saw when running your application locally. + +Since our application has both a `print` statement and and a middleware logger (provided by Shelf), we're able to inspect those logs in realtime from the dashboard. Click the "Logs" tab in the dashboard to view the logs for your deployment. Each time your refresh the deployment URL, a new log will appear in the dashboard! Any errors (which emit to `stderr`) will be highlighted in red. + +## Further reading + +- [Learn about to manage your deployments](/docs/deployments) +- [Learn about the Globe CLI](/docs/cli) +- [Integrate with GitHub](/docs/deployments/github-integration) diff --git a/docs/index.mdx b/docs/index.mdx new file mode 100644 index 00000000..7ecdb4a9 --- /dev/null +++ b/docs/index.mdx @@ -0,0 +1,43 @@ +--- +title: Getting started with Globe +--- + + + +Globe is a deployment platform for [Dart](https://dart.dev/) developers, that allows you to deploy your Dart applications to a globally +distributed service without the need to manage servers, networks, or scaling. The core principle of Globe is a simplified deployment service +with great developer experience in mind. + +## Features + +Some of the core features of Globe include: + +- **Deployments**: Deploy your Dart applications to Globe with a single command or automatically on every push to your Git repository. Globe supports both previewing and production deployments. +- **GitHub Integration**: Globe integrates with your existing CI/CD pipeline to automatically deploy your applications on every push to your Git repository. +- **Custom domains**: Assign custom domains to your projects, with SSL certificates automatically generated and renewed for you. +- **Organization support**: Globe supports organizations, allowing you to manage multiple projects and users under a single account. + +## Why Globe? + +Dart on the server is a great choice for building server based applications, such as APIs, websites, and more. The language has great support for building these applications with packages such +as [Shelf](https://pub.dev/packages/shelf) and [Dart Frog](https://pub.dev/packages/dart_frog) providing a great base for getting started. However, deploying these applications can be a challenge for +a number of reasons: + +- Developers require experience with cloud providers such as Google Cloud Platform (GCP), Amazon Web Services (AWS), Digital Ocean and more. +- Familiarity with tools such as Docker, Kubernetes, and Terraform is required to deploy applications. +- Critical components such as scaling, load balancing, and SSL certificates must be configured and monitored. +- Integrating with CI/CD flows can be challenging, especially when deploying multiple environments and preview deployments. +- This architecture comes with challenges such as managing cold starts, region based latency, and more. + +Globe aims to solve these problems by providing a simple, easy to use deployment platform for Dart developers. Globe utilizes a number of cloud providers to provide a globally distributed service with the following benefits: + +- Zero management overhead of servers, networking and scaling. +- Globally available regions. Globe deployments of your application are available around the world, providing low latency to your users and high availability. +- Globe automatically scales your application to meet demand. +- Built-in support for preview deployments, allowing you to preview every change, commit or PR before deploying to production. + +Simply run the `deploy` command or push to your Git repository and Globe will create a globally managed deployment for you within seconds. diff --git a/docs/infrastructure.cold-starts.mdx b/docs/infrastructure.cold-starts.mdx new file mode 100644 index 00000000..94f7e088 --- /dev/null +++ b/docs/infrastructure.cold-starts.mdx @@ -0,0 +1,32 @@ +--- +title: Cold Starts +--- + +# Cold Starts + +Globe infrastructure is built in a way to minimize and reduce the impact of cold starts. When a request starts a new container on demand this is known as a cold start. + +In Globe however we have 3 levels of 'starts'; + +- `cold` - Container image has to be fetched, cached and started. + - This is usually when your deployment has not yet had any requests in a specific compute region or has been idle for an extended period of time. +- `warm` - Container image is already fetched and cached but not started. + - This happens when a `hot` running container becomes idle for a period of time in a specific region and the running container is paused. +- `hot` - Container image is already fetched, cached and still running. + - This happens when requests in a specific region have kept the container from idling. + +Overall you should experience a reduced number of cold starts compared to other cloud providers as well as a reduced cold start time. During the private preview you can expect to see some cold starts of around 500ms. We're still working on reducing this number. + +## Mitigating cold starts + +Whilst it may not necessary for every application; there are a number of ways you can help mitigate the impact of cold starts specific to your deployment; + +- Reduce the size of your application by removing unnecessary dependencies and imports. + +## Detecting cold starts + +Each request to a Globe deployment has a custom header appended to it. The `x-globe-temperature` header will have a value of the start state: + +- `cold` +- `warm` +- `hot` diff --git a/docs/infrastructure.cron-jobs.mdx b/docs/infrastructure.cron-jobs.mdx new file mode 100644 index 00000000..05e27fad --- /dev/null +++ b/docs/infrastructure.cron-jobs.mdx @@ -0,0 +1,58 @@ +--- +title: Cron Jobs +--- + +# Cron Jobs + +Cron jobs can be used to periodically perform a HTTP request to your production Globe deployment. You can specify the cron schedule and the path to request. + +Cron jobs only work with production deployments. If your project does not have a production deployment, the cron execution will be ignored and no events will be shown. + +## Creating a Cron Job + +Cron jobs can be created via the `globe.yaml` file in the root of your application project, for example: + +```yaml +crons: + - id: refresh_auth_token + schedule: '0,45 * * * *' + path: '/auth/refresh' +``` + +In the above example, the cron job will be executed every 45 minutes. + +Whenever a new production deployment is successful, the cron jobs will be sychronized and shown in the dashboard. + +## Handling Cron Jobs + +Your application code should handle the cron job request via the path specified (`/auth/refresh` in the above example). The request will be a `POST` request. + +For example, using [`shelf_router`]() this can be achived as follows: + +```dart +import 'package:shelf_router/shelf_router.dart'; + +var app = Router(); + +app.post('/auth/refresh', (Request request) async { + // Some logic to refresh the auth token + return Response.ok('ok'); +}); +``` + +If a Cron Job returns a response with a status code other than one in the `2xx` range, this will show on the dashboard as an error. + +## Cron Job IDs + +The `id` field in the list represents the unique ID of the cron job. This is used to identify the cron job on the dashboard, and store event logs. +If a specific ID is removed, and later added, new event logs will be stored alongside any previous logs. Also note: + +- The list cannot contain duplicate IDs. +- The maximum length of an ID is 50 characters. +- The ID can only contain lowecase letters, numbers, and underscores (`a-z0-9_`). + +## Timezone + +At present, all cron jobs are executed in the UTC (Universal Coordinated Time) timezone, so you must take this into account when specifying the schedule. + +Please [upvote this feature request](https://invertase.canny.io/globe/p/custom-cron-job-timezones) if you would like support for custom timezones. diff --git a/docs/infrastructure.headers.mdx b/docs/infrastructure.headers.mdx new file mode 100644 index 00000000..a2060d99 --- /dev/null +++ b/docs/infrastructure.headers.mdx @@ -0,0 +1,27 @@ +--- +title: Headers +--- + +# Headers + +Each request to a deployment on Globe is automatically provided with a number of request headers which you could use in your application to customize how your application responds to the request. + +| **Header** | **Type** | **Description** | +| ---------------------- | :------: | --------------------------------------------------------------------------------------------------------- | +| `x-globe-request-id` | String | The unique ID for this request. | +| `x-globe-dc-id` | String? | The IATA code of where this request is executing. | +| `x-globe-dc-eu` | String? | A "true" or "false" string value of whether this request is executing within a data center within the EU. | +| `x-globe-dc-city` | String? | The data center city name of where this request is executing. | +| `x-globe-dc-country` | String | The data center ISO-3166-1 alpha-2 code of this request (e.g. "US"). | +| `x-globe-dc-continent` | String | The data center continent (e.g. "Europe"). | +| `x-globe-dc-latitude` | String | The data center location latitude. | +| `x-globe-dc-longitude` | String | The data center location longitude. | +| `x-globe-eu` | String? | A "true" or "false" string value of whether this request originated from within the EU. | +| `x-globe-latitude` | String? | The location latitude of where this request originated from. | +| `x-globe-longitude` | String? | The location longitude of where this request originated from. | +| `x-globe-city` | String? | The closest city of where this request originated from. | +| `x-globe-country` | String? | The ISO-3166-1 alpha-2 code of where this request originated from (e.g. "US"). | +| `x-globe-region` | String? | The location region of the incoming request (e.g. "Texas"). | +| `x-globe-region-code` | String? | The region code of the incoming request (as a ISO-3166-2 code e.g. "TX"). | +| `x-globe-continent` | String? | The continent of the incoming request (e.g. "Europe"). | +| `x-globe-tz` | String? | The location timezone of the incoming request, e.g. "America/Chicago". | diff --git a/docs/infrastructure.mdx b/docs/infrastructure.mdx new file mode 100644 index 00000000..5a9e0981 --- /dev/null +++ b/docs/infrastructure.mdx @@ -0,0 +1,87 @@ +--- +title: Infrastructure +--- + +# Infrastructure + +Globe is built on top of multiple cloud compute providers to provide a scalable and reliable service. The following sections provide an overview of the infrastructure used to run Globe & how you can integrate your Dart applications. + +## How it works + +Each time you create a new successful deployment, the Globe deployment service creates an executable of your Dart project. This executable is distributed to our global private deployment registry. + +When a user makes a request to your application, they first end up connecting to our global edge network (300+ locations). Our edge network provides zero latency routing management and allows us to route your user to the nearest [Globe compute region](/docs/infrastructure/regions) where our infrastructure will start a container in isolation on demand if necessary. + +Our edge network routing service is also responsible for features such as DDoS mitigation, instant rollbacks, A/B testing deployments and more. + +## Containers + +Globe uses container technology to start your Dart applications on demand. The platform will automatically scale your application based on the number of requests it receives. +Containers are created on demand in the closest [region](/docs/infrastructure/regions) to where a user request originates from. + +An on demand container environment means you should: + +- Not rely on having a persistent file system. +- Not rely on having persistent memory. + +Even if a user is performing multiple requests from the same region, it is not guaranteed that the same container will be used to handle the request. Treat each request as though it is a new environment. + +## Serverless + +Globe currently does not yet have a functions / serverless model, however we are experimenting providing this via upcoming technologies like WASM. Please consider providing your thoughts and your upvote on [this feature request](https://invertase.canny.io/globe/p/faas-serverless) if this is something that interests you. + +## Starting a server + +The Globe infrastructure expects that your Dart application starts listening to a port whenever executed. During the build phase of a deployment, +a check will take place to ensure that your application is listening to a port. If this is not the case, the deployment will fail. + +Using a package such as [shelf](https://pub.dev/packages/shelf), you can easily start a server which accepts in-bound HTTP requests by accessing +the `PORT` [environment variable](/docs/deployments/environment-variables): + +```dart +import 'dart:io'; + +import 'package:shelf/shelf.dart'; +import 'package:shelf/shelf_io.dart' as shelf_io; + +void main() async { + final handler = + const Pipeline().addHandler((Request request) { + return Response.ok('Hello, World!'); + }); + + final server = await shelf_io.serve( + handler, + // Use any IPv4 address. + InternetAddress.anyIPv4, + // Use the PORT environment variable. + int.tryParse(Platform.environment['PORT'] ?? '8080') ?? 8080, + ); +} +``` + +## Limitations + +Globe imposes a few request limits to ensure that the platform is not abused. + +#### File System + +You should only rely on the file system for temporary storage such as processing of files. Any files created during a request will be removed once the request is finished. + +#### Execution Timeout + +A single request is allowed to run for a maximum duration. If a request takes longer than the allowed duration, the request will be terminated. + +During private preview the maximum duration is currently **5 seconds**. We may increase this based on feedback and also allow higher limits for paid plans in future. + +#### CPU Usage + +You cannot perform CPU heavy tasks for an extended period of time (determined by the current infrastructure load). Any requests which exceed the allotted CPU usage will be terminated. + +#### Memory Usage + +Each container has a limited amount of memory available (128MB). Performing on-going memory heavy tasks may result in the request being terminated. We may increase this based on feedback and also allow higher limits for paid plans in future. + +#### FFI + +Usage of FFI (via `dart:ffi`) is not currently supported. We are working on providing this in future. diff --git a/docs/infrastructure.regions.mdx b/docs/infrastructure.regions.mdx new file mode 100644 index 00000000..2cb93975 --- /dev/null +++ b/docs/infrastructure.regions.mdx @@ -0,0 +1,90 @@ +--- +title: Regions +--- + +# Regions + +The Globe edge network is located in some [300 cities in 100+ countries](https://www.cloudflare.com/en-gb/network/) and is powered by Cloudflare’s network - which is milliseconds away from virtually every Internet user on the globe. + +Our edge network is responsible for features such as DDoS mitigation, zero latency routing to our compute regions, instant rollbacks, A/B testing deployments and more. + +## Compute Regions + +Globe runs your deployments in 37 (currently) compute regions. + +
+ Compute Regions + +| **Region** | **Country** | **Continent** | +| ----------------------- | -------------- | ------------- | +| MAD (Madrid) | Spain | Europe | +| BRU (Belgium) | Belgium | Europe | +| AMS (Netherlands) | Netherlands | Europe | +| MXP (Milan) | Italy | Europe | +| CDG (Paris) | France | Europe | +| TPE (Taiwan) | Taiwan | Asia | +| NRT (Tokyo) | Japan | Asia | +| KIX (Osaka) | Japan | Asia | +| HEL (Finland) | Finland | Europe | +| TLV (Tel Aviv) | Israel | Asia | +| DSM (Iowa) | United States | North America | +| CHS (South Carolina) | United States | North America | +| IAD (Northern Virginia) | United States | North America | +| CMH (Columbus) | United States | North America | +| DFW (Dallas) | United States | North America | +| PDX (Oregon) | United States | North America | +| HKG (Hong Kong) | Hong Kong | Asia | +| ICN (Seoul) | South Korea | Asia | +| SIN (Singapore) | Singapore | Asia | +| CGK (Jakarta) | Indonesia | Asia | +| BOM (Mumbai) | India | Asia | +| DEL (Delhi) | India | Asia | +| SYD (Sydney) | Australia | Oceania | +| MEL (Melbourne) | Australia | Oceania | +| WAW (Warsaw) | Poland | Europe | +| TRN (Turin) | Italy | Europe | +| LHR (London) | United Kingdom | Europe | +| FRA (Frankfurt) | Germany | Europe | +| ZRH (Zurich) | Switzerland | Europe | +| DOH (Doha) | Qatar | Asia | +| YUL (Montreal) | Canada | North America | +| YYZ (Toronto) | Canada | North America | +| GRU (Sao Paulo) | Brazil | South America | +| SCL (Santiago) | Chile | South America | +| LAX (Los Angeles) | United States | North America | +| SLC (Salt Lake City) | United States | North America | +| LAS (Las Vegas) | United States | North America | + +
+ +Globe compute regions will continue expanding into the following regions: Berlin (Germany), Dammam (Kingdom of Saudi Arabia), Querétaro (Mexico), Malaysia, Thailand, New Zealand, Greece, Norway, South Africa, Austria and Sweden. + +## Preferred Regions + +In some cases, executing a request in a region closest to the user may not be desirable. Consider a user who hits your application from Europe but your application uses a region specific database located in the United States. + +Multiple outbound requests from Europe to the US data center could result in potentially long response times for +the user whilst data is sent across the network. In this scenario, it may make more sense to handle the request in the US data center, and then +return the response to the user from there. + +This can be achieved by specifying preferred region(s). When preferred regions are specified Globe will: + +- if a single preferred region is provided: execute the request in the preferred region + - if the specified region is unhealthy or experiencing an outage, then default global routing behavior is used and the nearest healthy region executes the request. +- if multiple regions are provided, Globe will choose the closest preferred region to the user and execute the request there + - if any of specified regions are unhealthy or experiencing an outage, they will no longer be preferred. + - if all of the specified regions are unhealthy or experiencing an outage, then default global routing behavior is used and the nearest healthy region executes the request. + +### Configure via Project Settings + +Within the Globe dashboard, under **Project** -> **Settings** -> **Preferred Region**, you can select a preferred region for your project. + +When selecting preferred regions from the dashboard, this will only apply to new deployments. + +### Configure via `X-Globe-Preferred-Region` header + +Specify IATA codes from the region list in the `X-Globe-Preferred-Region` header of a request. + +For example: `X-Globe-Preferred-Region: DFW, PDX` + +Note that when specifying a preferred region via the header this will override any preferred region(s) set in the Project Settings dashboard. diff --git a/docs/infrastructure.websockets.mdx b/docs/infrastructure.websockets.mdx new file mode 100644 index 00000000..12e59474 --- /dev/null +++ b/docs/infrastructure.websockets.mdx @@ -0,0 +1,11 @@ +--- +title: Web Sockets +--- + +# Web Sockets + +We Sockets enable you to open a two-way interactive communication session between your clients and server. This is a great way to build real-time applications like chat, games, and monitoring tools. + +Globe has currently disabled Web Sockets connections whilst we monitor our infrastructure during the private preview period. + +If you would like to use this feature, please consider providing your thoughts/use cases and your upvote on this [feature request](https://invertase.canny.io/globe/p/web-socket-support).