diff --git a/docs.yaml b/docs.yaml index 7e5b7b54..a62ed981 100644 --- a/docs.yaml +++ b/docs.yaml @@ -18,47 +18,47 @@ sidebar: - - - CLI Overview - "/cli" - - Deploy - - "/cli.commands.deploy" + - "/cli/commands/deploy" - - Link - - "/cli.commands.link" + - "/cli/commands/link" + - - Unlink + - "/cli/commands/unlink" - - Login - - "/cli.commands.login" + - "/cli/commands/login" - - Logout - - "/cli.commands.logout" - - - Unlink - - "/cli.commands.unlink" + - "/cli/commands/logout" - - Deployments - - - Overview - "/deployments" - - Build Settings - - "/deployments.build-settings" + - "/deployments/build-settings" - - Domains - - "/deployments.domains" + - "/deployments/domains" - - Environment Variables - - "/deployments.environment-variables" + - "/deployments/environment-variables" - - GitHub Integration - - "/deployments.github-integration" + - "/deployments/github-integration" - - Hooks - - "/deployments.hooks" + - "/deployments/hooks" - - Redeployments - - "/deployments.redeployments" + - "/deployments/redeployments" - - Frameworks - - - Overview - "/frameworks" - - Dart Frog - - "/frameworks.dart-frog" + - "/frameworks/dart-frog" - - Jaspr - - "/frameworks.jaspr" + - "/frameworks/jaspr" - - Infrastructure - - - Overview - "/infrastructure" - - Cold Starts - - "/infrastructure.cold-starts" + - "/infrastructure/cold-starts" - - Cron Jobs - - "/infrastructure.cron-jobs" + - "/infrastructure/cron-jobs" - - Headers - - "/infrastructure.headers" + - "/infrastructure/headers" - - Regions - - "/infrastructure.regions" + - "/infrastructure/regions" - - WebSockets - - "/infrastructure.websockets" \ No newline at end of file + - "/infrastructure/websockets" diff --git a/docs/cli.commands.logout.mdx b/docs/cli.commands.logout.mdx deleted file mode 100644 index 452bd1f4..00000000 --- a/docs/cli.commands.logout.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -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.deploy.mdx b/docs/cli/commands/deploy.mdx similarity index 67% rename from docs/cli.commands.deploy.mdx rename to docs/cli/commands/deploy.mdx index 281f5a41..36c3e73e 100644 --- a/docs/cli.commands.deploy.mdx +++ b/docs/cli/commands/deploy.mdx @@ -7,7 +7,7 @@ description: Deploy your Dart application to Globe directly from the command lin 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. +If you have not yet [linked a project](/cli/commands/link), you will be prompted to do so before deploying. ## Usage @@ -19,7 +19,7 @@ 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. +By default, deployments via the `deploy` command are treated as a preview deployment. This means that once deployed, the deployment will have its own unique URL generated by Globe. To deploy as a production deployment, append the `--prod` flag to the command. ```bash @@ -28,10 +28,10 @@ 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. +You can learn more about [preview and production deployments](/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 --`: +The command has flags (in addition to [global flags](/cli#global-flags)) 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. +- `--prod` - Creates a deployment that will be promoted to production once built. diff --git a/docs/cli.commands.link.mdx b/docs/cli/commands/link.mdx similarity index 61% rename from docs/cli.commands.link.mdx rename to docs/cli/commands/link.mdx index 945f9d65..3c47eb3f 100644 --- a/docs/cli.commands.link.mdx +++ b/docs/cli/commands/link.mdx @@ -6,7 +6,7 @@ title: Link a project to Globe 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. +Project linking is carried out automatically if the project is not yet linked when running the [`deploy`](/cli/commands/deploy) command. ## Usage @@ -16,14 +16,14 @@ 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. +1. Select an account you wish to link this local project to. +2. Select, or create a new project to link this local project to. -Upon completion, the project will be linked to your Globe account and you will be able to deploy the project. +Upon completion, the local project will be linked to your Globe account and you will be able to deploy it. -## Details +## How it works 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. +If you accidentally delete this directory or run the [`unlink`](/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 similarity index 86% rename from docs/cli.commands.login.mdx rename to docs/cli/commands/login.mdx index 1c9213a2..0cb5847c 100644 --- a/docs/cli.commands.login.mdx +++ b/docs/cli/commands/login.mdx @@ -15,7 +15,7 @@ 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: +If you wish to [logout](/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..46613740 --- /dev/null +++ b/docs/cli/commands/logout.mdx @@ -0,0 +1,15 @@ +--- +title: Logout of Globe +--- + +# Logout + +The `logout` command 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 similarity index 96% rename from docs/cli.commands.unlink.mdx rename to docs/cli/commands/unlink.mdx index 149b2b16..0fffcfb0 100644 --- a/docs/cli.commands.unlink.mdx +++ b/docs/cli/commands/unlink.mdx @@ -12,6 +12,6 @@ The `unlink` command removes any previously linked projects from the current loc globe unlink ``` -## Details +## How it works 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/index.mdx similarity index 100% rename from docs/cli.mdx rename to docs/cli/index.mdx diff --git a/docs/deployments.hooks.mdx b/docs/deployments.hooks.mdx deleted file mode 100644 index 4bfd01dc..00000000 --- a/docs/deployments.hooks.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -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 deleted file mode 100644 index c9f45bf6..00000000 --- a/docs/deployments.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -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](/assets/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.build-settings.mdx b/docs/deployments/build-settings.mdx similarity index 50% rename from docs/deployments.build-settings.mdx rename to docs/deployments/build-settings.mdx index 590586c7..ee8c274f 100644 --- a/docs/deployments.build-settings.mdx +++ b/docs/deployments/build-settings.mdx @@ -4,7 +4,7 @@ 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**. +Build settings allow you to configure how your project is built during a new deployment. You can configure your build settings via the dashboard: **Project** -> **Settings** -> **General**. ![Project Settings](/assets/project-settings.png) @@ -12,17 +12,17 @@ Build settings allow you to configure how your project is build during a new dep 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](/deployments/build-settings#dart-version) +- [Root Directory](/deployments/build-settings#root-directory) +- [Framework Preset](/deployments/build-settings#framework-preset) +- [Build Command](/deployments/build-settings#build-command) +- [Entrypoint](/deployments/build-settings#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. +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. @@ -30,13 +30,13 @@ 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. +The root directory is the directory that 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. +Globe supports existing [frameworks](/frameworks). If a framework is specified here, Globe will use the 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. --- @@ -50,7 +50,7 @@ If using a **Framework Preset**, a default value will be used instead. You can o ### 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 +When building your application, the build system requires an entrypoint file which is used to bootstrap your application. This 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. diff --git a/docs/deployments.domains.mdx b/docs/deployments/domains.mdx similarity index 71% rename from docs/deployments.domains.mdx rename to docs/deployments/domains.mdx index fd69f7f2..4be5fed3 100644 --- a/docs/deployments.domains.mdx +++ b/docs/deployments/domains.mdx @@ -6,7 +6,7 @@ title: 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. +Each deployment, production or preview gets assigned a unique domain that 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 diff --git a/docs/deployments.environment-variables.mdx b/docs/deployments/environment-variables.mdx similarity index 91% rename from docs/deployments.environment-variables.mdx rename to docs/deployments/environment-variables.mdx index 85c2a78a..1dbfc2db 100644 --- a/docs/deployments.environment-variables.mdx +++ b/docs/deployments/environment-variables.mdx @@ -4,7 +4,7 @@ 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 +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 that 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 diff --git a/docs/deployments.github-integration.mdx b/docs/deployments/github-integration.mdx similarity index 100% rename from docs/deployments.github-integration.mdx rename to docs/deployments/github-integration.mdx diff --git a/docs/deployments/hooks.mdx b/docs/deployments/hooks.mdx new file mode 100644 index 00000000..57f56e04 --- /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 that will be called throughout the lifecycle of a deployment, for example +when a deployment is created, built, or deployed. + +Deployment hooks are in development feature and will be available soon. diff --git a/docs/deployments/index.mdx b/docs/deployments/index.mdx new file mode 100644 index 00000000..c6ef884d --- /dev/null +++ b/docs/deployments/index.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](/deployments#creating-a-production-deployment) or [Preview](/deployments#creating-a-preview-deployment). +When a Production deployment has been successfully built, your domains will be updated automatically to point to the new deployment. Preview deployments on the other hand 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](/assets/deployments.png) + +Once deployments have been 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`](/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](/deployments/github-integration), you can trigger a preview deployment by pushing to a branch that +is not defined as the production branch in your project settings. + +To learn more, view the [GitHub Integration](/deployments/github-integration) documentation. + +## Creating a production deployment + +To create a new production deployment, you have two options: + +### via the CLI + +Run the [`deploy`](/cli/commands/deploy) command with the `--prod` flag: + +```bash +globe deploy --prod +``` + +### via GitHub + +Using the [GitHub Integration](/deployments/github-integration), you can trigger a production deployment by pushing to the branch +specified in your project settings. By default, this is the `main` branch. + +To learn more, view the [GitHub Integration](/deployments/github-integration) documentation. diff --git a/docs/deployments.redeployments.mdx b/docs/deployments/redeployments.mdx similarity index 100% rename from docs/deployments.redeployments.mdx rename to docs/deployments/redeployments.mdx diff --git a/docs/frameworks.mdx b/docs/frameworks.mdx deleted file mode 100644 index 301ccc1b..00000000 --- a/docs/frameworks.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -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/frameworks.dart-frog.mdx b/docs/frameworks/dart-frog.mdx similarity index 100% rename from docs/frameworks.dart-frog.mdx rename to docs/frameworks/dart-frog.mdx diff --git a/docs/frameworks/index.mdx b/docs/frameworks/index.mdx new file mode 100644 index 00000000..9870873c --- /dev/null +++ b/docs/frameworks/index.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 run before deployment. Globe supports these frameworks by automatically providing default build settings for each framework that can be used to build and deploy your application. + +## Supported Frameworks + +Ongoing 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](/frameworks/dart-frog) +- [Jaspr](/frameworks/jaspr) diff --git a/docs/frameworks.jaspr.mdx b/docs/frameworks/jaspr.mdx similarity index 100% rename from docs/frameworks.jaspr.mdx rename to docs/frameworks/jaspr.mdx diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx index c1497b9b..e026f827 100644 --- a/docs/getting-started.mdx +++ b/docs/getting-started.mdx @@ -4,12 +4,18 @@ 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. +To get started using Globe, ensure you have [logged in](https://globe.dev/login) to your account. ## 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. +#### 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 @@ -24,11 +30,11 @@ To login with your Globe account, run the following command: globe login ``` -To learn more about the CLI, view the [documentation](/docs/cli). +To learn more about the CLI, view the [documentation](/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: +To get started, we're going to create a simple Dart application that will be deployed to Globe. We'll use [Shelf](https://pub.dev/packages/shelf) to start an HTTP server that 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 @@ -79,19 +85,19 @@ globe deploy The first time you deploy, you'll: -1. Be prompted to continue with setup of the deployment (press `Y`) +1. Be prompted to continue with the 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. +Once complete, your deployment will be available via the URL shown in the dashboard. Each deployment has its own unique URL, with a `globeapp.dev` domain. Click the URL and you'll be shown the `Request for "hello"... worked!` message that you 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. +Since our application has both a `print` statement 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 you 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) +- [Learn about managing your deployments](/deployments) +- [Learn about the Globe CLI](/cli) +- [Integrate with GitHub](/deployments/github-integration) diff --git a/docs/index.mdx b/docs/index.mdx index 7ecdb4a9..2ab3c476 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -1,12 +1,8 @@ --- -title: Getting started with Globe +title: Globe Overview --- - +# What is 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 @@ -16,14 +12,14 @@ with great developer experience in mind. 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. +- [Deployments][deployment-url]: Deploy your Dart applications to Globe with a single command or automatically on every push to your Git repository. Globe supports both [preview][preview-url] and [production][production-url] deployments. +- [GitHub Integration][github-integration-url]: Globe integrates with your existing github repository to automatically deploy your applications on every push. +- [Custom domains][custom-domains-url]: 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 +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: @@ -31,7 +27,7 @@ a number of reasons: - 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. +- 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: @@ -41,3 +37,9 @@ Globe aims to solve these problems by providing a simple, easy to use deployment - 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. + +[deployment-url]: /deployments +[github-integration-url]: /deployments/github-integration +[custom-domains-url]: /domains#custom-domains +[preview-url]: /deployments#creating-a-preview-deployment +[production-url]: /deployments#creating-a-production-deployment diff --git a/docs/infrastructure.cold-starts.mdx b/docs/infrastructure/cold-starts.mdx similarity index 78% rename from docs/infrastructure.cold-starts.mdx rename to docs/infrastructure/cold-starts.mdx index 94f7e088..6e6e9f9f 100644 --- a/docs/infrastructure.cold-starts.mdx +++ b/docs/infrastructure/cold-starts.mdx @@ -6,7 +6,7 @@ title: 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'; +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. @@ -15,11 +15,11 @@ In Globe however we have 3 levels of 'starts'; - `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. +Overall you should experience a reduced number of cold starts compared to other cloud providers as well as reduced cold start times. 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; +Whilst it may not be 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. diff --git a/docs/infrastructure.cron-jobs.mdx b/docs/infrastructure/cron-jobs.mdx similarity index 83% rename from docs/infrastructure.cron-jobs.mdx rename to docs/infrastructure/cron-jobs.mdx index 61a9fea8..9b9da3a8 100644 --- a/docs/infrastructure.cron-jobs.mdx +++ b/docs/infrastructure/cron-jobs.mdx @@ -4,9 +4,9 @@ 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 can be used to periodically perform an 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. +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 @@ -15,7 +15,7 @@ Cron jobs can be created via the `globe.yaml` file in the root of your applicati ```yaml crons: - id: refresh_auth_token - schedule: '0,45 * * * *' + schedule: '0/45 * * * *' path: '/auth/refresh' ``` diff --git a/docs/infrastructure.headers.mdx b/docs/infrastructure/headers.mdx similarity index 89% rename from docs/infrastructure.headers.mdx rename to docs/infrastructure/headers.mdx index a2060d99..bb731a60 100644 --- a/docs/infrastructure.headers.mdx +++ b/docs/infrastructure/headers.mdx @@ -11,7 +11,7 @@ Each request to a deployment on Globe is automatically provided with a number of | `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-city` | String? | The data center city name of where this request is executed. | | `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. | @@ -19,9 +19,9 @@ Each request to a deployment on Globe is automatically provided with a number of | `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-city` | String? | The closest city 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-region-code` | String? | The region code of the incoming request (as an 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/index.mdx similarity index 74% rename from docs/infrastructure.mdx rename to docs/infrastructure/index.mdx index 5a9e0981..575e2ed4 100644 --- a/docs/infrastructure.mdx +++ b/docs/infrastructure/index.mdx @@ -10,16 +10,16 @@ Globe is built on top of multiple cloud compute providers to provide a scalable 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. +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](/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. +Containers are created on demand in the closest [region](/infrastructure/regions) to where a user request originates from. -An on demand container environment means you should: +An on-demand container environment means you should: - Not rely on having a persistent file system. - Not rely on having persistent memory. @@ -28,15 +28,15 @@ Even if a user is performing multiple requests from the same region, it is not g ## 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. +Globe currently does not yet have a functions / serverless model, however, we are experimenting with 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): +Using a package such as [shelf](https://pub.dev/packages/shelf), you can easily start a server that accepts inbound HTTP requests by accessing +the `PORT` [environment variable](/deployments/environment-variables): ```dart import 'dart:io'; @@ -72,16 +72,16 @@ You should only rely on the file system for temporary storage such as processing 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. +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 the 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. +You cannot perform CPU heavy tasks for an extended period of time (determined by the current infrastructure load). Any requests that 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. +Each container has a limited amount of memory available (128MB). Performing ongoing 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 the future. #### FFI -Usage of FFI (via `dart:ffi`) is not currently supported. We are working on providing this in future. +Usage of FFI (via `dart:ffi`) is not currently supported. We are working on providing this in the future. diff --git a/docs/infrastructure.regions.mdx b/docs/infrastructure/regions.mdx similarity index 89% rename from docs/infrastructure.regions.mdx rename to docs/infrastructure/regions.mdx index 2cb93975..375ccb15 100644 --- a/docs/infrastructure.regions.mdx +++ b/docs/infrastructure/regions.mdx @@ -4,7 +4,7 @@ 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. +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][cloudflare-network-url] - 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. @@ -61,13 +61,13 @@ Globe compute regions will continue expanding into the following regions: Berlin ## 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. +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: +This can be achieved by specifying the 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. @@ -77,7 +77,7 @@ This can be achieved by specifying preferred region(s). When preferred regions a ### Configure via Project Settings -Within the Globe dashboard, under **Project** -> **Settings** -> **Preferred Region**, you can select a preferred region for your project. +Within the Globe dashboard, under **Projects** -> **Select 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. @@ -88,3 +88,5 @@ Specify IATA codes from the region list in the `X-Globe-Preferred-Region` header 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. + +[cloudflare-network-url]: https://www.cloudflare.com/network/ diff --git a/docs/infrastructure.websockets.mdx b/docs/infrastructure/websockets.mdx similarity index 64% rename from docs/infrastructure.websockets.mdx rename to docs/infrastructure/websockets.mdx index 12e59474..0a2a9890 100644 --- a/docs/infrastructure.websockets.mdx +++ b/docs/infrastructure/websockets.mdx @@ -4,7 +4,7 @@ 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. +Web 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.