Update documentation website + home README (#134)

- Reorganises all of our current docs into docs pages on the docs
website
- Adds more documentation around "how linkup works" and "what is a
preview environment"
- Links to the documentation website from the main readme instead

README.md

@@ -1,112 +1,17 @@
-# linkup
 
-> Run the services you change, get the rest for free
+<h1  align="center" style="font-size: 3em;">🔗 Linkup</h1>
 
-Linkup lets you combine local and remote services to create cheap yet complete development environments.
-
-Linkup is written in rust, and uses a combination of cloudflare workers and tunnels under the hood.
-
-## How it works
-
-Engineers often need a complete copy of a system to develop on, even though they only change one or two services at a time.
-
-Linkup lets you create many "virtual copies" of a system, each with a different set of services running locally and remotely. We call each unique virtual copy a _linkup session_.
-
-![linkup-routing](./docs/src/assets/linkup-routing.svg)
-
-For example, Peter here can use a local copy of their web development server, but they can use the remote / shared backend server without having to run anything locally.
-
-Mary's pull request can deploy a preview of their backend that can be accessed through the remote / shared web server.
-
-## Using Linkup
-
-**There is more detailed information about running and debugging linkup sessions in [docs/using-linkup](./docs/using-linkup.md)**
-
-To use link up locally the easiest way to get started is to use the linkup cli:
-
-```sh
-brew tap mentimeter/mentimeter
-brew install linkup
-```
-
-Once you have the cli installed you can start a linkup session by running:
+<img src="https://img.shields.io/badge/documentation-available-brightgreen" alt="Documentation">
 
-```zsh
-linkup start      <--- Gives you your unique session name
-linkup status     <--- Shows how your session is configured
-linkup local web  <--- Routes traffic of the `web` service to your local machine
-linkup stop       <-- Stops your session
-```
+<br/>
 
-## Configuring Linkup
+> Run the services you change, get the rest for free.
 
-Linkup is configured using a yaml file when you start your linkup session. This file describes the services that make up your system, and how they should be combined into linkup sessions.
-
-Here is an example:
-
-```yaml
-linkup:
-  remote: https://where.linkup.is.deployed.com
-  # By default, linkup will ensure _nothing_ is cached for dev environments
-  # to update on save, you can override this behaviour for specific paths
-  # by adding them to the cache_routes list
-  cache_routes:
-    - .*/_next/static/.*
-    - .*/_next/data/.*
-services:
-  - name: web
-    remote: https://web-dev.hosting-provider.com
-    local: http://localhost:3000
-    # Can be used to rewrite request paths
-    rewrites:
-      - source: /foo/(.*)
-        target: /bar/$1
-  - name: backend
-    remote: https://api-dev.hosting-provider.com
-    local: http://localhost:9000
-    directory: ./relative/path/to/backend
-domains:
-  - domain: dev-domain.com
-    default_service: web
-    routes:
-      - path: /api/v1/.*
-        service: backend
-  - domain: api.dev-domain.com
-    default_service: backend
-```
-
-### Local environment variables
-
-When booting local servers to run in linkup, they must be configured with environment variables that point to your linkup domain.
-
-To do this, linkup appends the contents of `.env.linkup` to the `.env` file located in the `directory` configuration field of the service.
-
-Linkup will fail to start if there is no `.env.linkup` file, and it will warn you to restart your local server if it was already booted on `linkup start`.
-
-## Deploying Linkup
-
-In order to run linkup sessions, you need:
-
-- A dedicated domain for the linkup cloudflare worker to run on
-- Deployed copies of the remote services you want to provide
-
-### Configuring the domain & worker
-
-Linkup is deployed as a cloudflare worker with a key-value store, and can be deployed using the wrangler cli:
-
-```sh
-cd worker
-cp wrangler.toml.sample wrangler.toml
-# Edit wrangler.toml to point to your cf kv store
-npx wrangler@latest deploy
-```
+Linkup lets you combine local and remote services to create cheap yet complete development environments.
 
-It is also easiest to use a domain in cloudflare. Set the `*` and `*.*` subdomains to point to the worker you just deployed.
 
-### Deploying remote services
+Linkup is written in Rust, and uses a combination of Cloudflare Workers and tunnels under the hood.
 
-The remote services you would like to make available to linkup sessions have a few requirements:
+---
 
-- They must be accessible at a public url
-- Their environment variables must be configured to point to your linkup domain
-- For requests _from_ the remote service to be correctly routed to linkup sessions, they must be able to [propagate trace contexts](https://www.w3.org/TR/trace-context/) through requests made from the service. The easiest way to acheive this is to use an OpenTelemetry client library to instrument your http client. Here is [an example for javascript](https://www.npmjs.com/package/@opentelemetry/instrumentation-http).
+🌐 [Documentation](https://mentimeter.github.io/linkup)

docs/astro.config.mjs

@@ -13,18 +13,18 @@ export default defineConfig({
         github: "https://github.com/mentimeter/linkup",
       },
       sidebar: [
+        {
+          label: "Explanations",
+          autogenerate: { directory: "explanation" },
+        },
         {
           label: "How To Guides",
-          autogenerate: { directory: "how-to" },
+          autogenerate: { directory: "guides" },
         },
         {
           label: "Tutorials",
           autogenerate: { directory: "tutorials" },
         },
-        {
-          label: "Explanations",
-          autogenerate: { directory: "explanation" },
-        },
         {
           label: "Reference",
           autogenerate: { directory: "reference" },

docs/src/content/docs/explanation/how-it-works.md

@@ -0,0 +1,26 @@
+---
+title: How does Linkup work?
+description: How to configure services to work with Linkup
+---
+
+## Linkup Sessions and Subdomains
+
+Whenever you create a new linkup session, either for a local environment or for a preview environment, you will receive a unique linkup session name, which is a subdomain of your linkup domain.
+
+For example, `linkup start` might give you a `slim-gecko.example.com` (local environment) subdomain. Or `linkup preview` might give you `xyz123.example.com` (preview environment) subdomain.
+
+This linkup session name will be used to identify all of the requests that belong to that session.
+
+## Identifying Requests to Sessions
+
+All requests that reach linkup go through an identification process to determine which session they belong to. Requests that can't be identified are rejected as a precaution.
+
+Request to session identification uses two methods:
+
+- Common browser headers, primarily `Referer`.
+- Opentelemetry tracing headers `traceparent` and `tracestate`.
+
+For all requests you make within a linkup session, they will either come straight from the browser (identified by your linkup subdomain `slim-ant.domain.com`), or they will come from an underlying service.
+
+Linkup will add opentelemetry tracing headers to all requests it receives, but you will likely need to _propogate_ these headers through your services. Please refer to the [OpenTelemetry documentation on how to do this for your specific language and framework](https://opentelemetry.io/docs/languages/).
+

docs/src/content/docs/explanation/what-is-linkup.md

@@ -0,0 +1,23 @@
+---
+title: What is Linkup?
+description: An explanation of linkups layout and purpose
+sidebar:
+  order: 1
+---
+
+Most modern web applications consist of many services.
+
+Engineers often need a complete copy of a these services to develop and test changes on, even though they only change one or two services at a time.
+
+Linkup reduces the cost of running a complete system copy by combining shared, persistent services with _changed_ services that can run locally or in temporary "preview" environments.
+
+Each "virtual copy" of a system is called a _linkup session_.
+
+![linkup-routing](../../../assets/linkup-routing.png)
+
+For example, Peter here can use a local copy of their web development server, but they can use the remote / shared backend server without having to run anything locally.
+
+Mary's pull request can deploy a preview of their backend that can be accessed through the remote / shared web server.
+
+
+

docs/src/content/docs/guides/configure.md

@@ -0,0 +1,55 @@
+---
+title: Configuring Linkup
+description: Using a linkup configuration file to describe the layout of your services
+---
+
+## Configuring Linkup
+
+Linkup is configured using a yaml file when you start your linkup session. This file describes the services that make up your system, and how they should be combined into linkup sessions.
+
+Here is an example:
+
+```yaml
+linkup:
+  remote: https://where.linkup.is.deployed.com
+  # By default, linkup will ensure _nothing_ is cached for dev environments
+  # to update on save, you can override this behaviour for specific paths
+  # by adding them to the cache_routes list
+  cache_routes:
+    - .*/_next/static/.*
+    - .*/_next/data/.*
+services:
+  - name: web
+    remote: https://web-dev.hosting-provider.com
+    local: http://localhost:3000
+    # Can be used to rewrite request paths
+    rewrites:
+      - source: /foo/(.*)
+        target: /bar/$1
+  - name: backend
+    remote: https://api-dev.hosting-provider.com
+    local: http://localhost:9000
+    directory: ./relative/path/to/backend
+domains:
+  - domain: dev-domain.com
+    default_service: web
+    routes:
+      - path: /api/v1/.*
+        service: backend
+  - domain: api.dev-domain.com
+    default_service: backend
+```
+
+### Local environment variables
+
+When booting local servers to run in linkup, they must be configured with environment variables that point to your linkup domain.
+
+To do this, linkup appends the contents of `.env.linkup` to the `.env` file located in the `directory` configuration field of the service.
+
+### Deploying remote services
+
+The remote services you would like to make available to linkup sessions have a few requirements:
+
+- They must be accessible at a public url
+- Their environment variables must be configured to point to your linkup domain
+- For requests _from_ the remote service to be correctly routed to linkup sessions, they must be able to [propagate trace contexts](https://www.w3.org/TR/trace-context/) through requests made from the service. The easiest way to acheive this is to use an OpenTelemetry client library to instrument your http client. Here is [an example for javascript](https://www.npmjs.com/package/@opentelemetry/instrumentation-http).

docs/src/content/docs/guides/deploy-linkup.md

@@ -0,0 +1,29 @@
+---
+title: Deploy Linkup to Cloudflare
+description: Deploy the remote linkup worker to a Cloudflare domain
+---
+
+## Prerequisites
+
+- A Cloudflare account
+- A domain connected to your Cloudflare account that you can use for linkup
+
+## Deploying Linkup
+
+In order to run linkup sessions, you need:
+
+- A dedicated domain for the linkup cloudflare worker to run on
+- Deployed copies of the remote services you want to provide
+
+### Configuring the domain & worker
+
+Linkup is deployed as a cloudflare worker with a key-value store, and can be deployed using the wrangler cli:
+
+```sh
+cd worker
+cp wrangler.toml.sample wrangler.toml
+# Edit wrangler.toml to point to your cf kv store
+npx wrangler@latest deploy
+```
+
+It is also easiest to use a domain in cloudflare. Set the `*` and `*.*` subdomains to point to the worker you just deployed.

docs/src/content/docs/guides/local-dns.md

@@ -0,0 +1,19 @@
+---
+title: Using Local DNS
+description: Use local DNS to speed up local linkup environments
+---
+
+## Speeding up your linkup session with `local-dns`
+
+Your linkup domains live on the public internet. If you're running heavy frontend servers that load 50mb of js assests, you might find that your linkup session feels slow.
+
+Linkup comes with a public-internet-bypass mechanism called `local-dns`. This feature allows you to resolve your linkup domains to your local machine, bypassing the public internet. This will make your frontends serve assets from your local machine, and make your linkup session feel much faster.
+
+To use `local-dns`, run `linkup local-dns install` in your terminal. This will install a local DNS server on your machine that will resolve your linkup domains to your local machine.
+
+### Limitations of `local-dns`
+
+Although much of your traffic will be served from your local machine, some requests will still go through the internet, and therefore still need a functioning tunnel, including:
+
+- When accessing a linkup session from a different device or from a colleague's machine.
+- When a remote service needs to access a server on your local machine (a remote frontend making a network request to your local backend).

docs/src/content/docs/guides/local-env.md

@@ -0,0 +1,28 @@
+---
+title: Run a Local Linkup Session 
+description: Get started with linkup by running a local linkup session
+sidebar:
+  order: 1
+---
+
+## Prerequisites
+
+- [Linkup deployed to a Cloudflare domain](/linkup/guides/deploy-linkup)
+
+## Installing the CLI
+
+To use link up locally the easiest way to get started is to use the linkup cli:
+
+```sh
+brew tap mentimeter/mentimeter
+brew install linkup
+```
+
+Once you have the cli installed you can start a linkup session by running:
+
+```zsh
+linkup start      <--- Gives you your unique session name
+linkup status     <--- Shows how your session is configured
+linkup local web  <--- Routes traffic of the `web` service to your local machine
+linkup stop       <-- Stops your session
+```

docs/src/content/docs/guides/preview-env.md

@@ -0,0 +1,41 @@
+---
+title: Create a Preview Environment
+description: Connect remote services to a persistent linkup preview environment
+---
+
+### Prerequisites
+
+- Linkup deployed to a Cloudflare Domain
+
+### What is a Preview Environment?
+
+`linkup start` is designed to:
+
+- work with services that you run _locally_ (on localhost)
+- run with a tunnel that makes your local service available on the internet
+- only be used by one engineer (not available when dev laptop is off)
+
+A preview environment on the other hand:
+
+- consists only of services deployed to the internet (eg. `my-deploy-pr-123.previewinfra.com`)
+- has no tunnels or tunneling infrastructure to `localhost`
+- always online / works as long as the underlying services do
+
+### Creating a preview environment
+
+```
+linkup preview
+
+Create a "permanent" Linkup preview
+
+Usage: linkup preview [OPTIONS] <SERVICES>...
+
+Arguments:
+  <SERVICES>...  <service>=<url> pairs to preview.
+```
+
+For example:
+
+```
+linkup preview web=https://my-preview-deploy-123.example.com
+```