Update content (superfly#1888)

getting-started/index.html.md

@@ -5,6 +5,10 @@ nav: firecracker
 toc: false
 ---
 
+<figure class="flex justify-center">
+  <img src="/static/images/get-started.png" alt="Illustration by Annie Ruygt of a bird reading from a book" class="max-w-lg">
+</figure>
+
 Get up and running on Fly.io:
 
 - **[Quickstart](/docs/getting-started/launch/):** Launch your own app now.
@@ -17,10 +21,6 @@ Get up and running on Fly.io:
 
 - **[Fly.io essentials](/docs/getting-started/essentials):** A primer on Fly Machines and Fly Launch, plus the Fly.io glossary. It's all here.
 
-<figure>
-  <img src="/static/images/docs-guide.webp" srcset="/static/images/[email protected] 2x" alt="Illustration by Annie Ruygt of a chair and a small table holding a hot drink, on a rooftop, with a city skyline and hot-air balloons in the background">
-</figure>
-
 ## Learn more
 
 * [Fly Launch](/docs/apps): You've tried the `fly launch` command. Now learn how to use all the Fly Launch features that help you manage and run your apps.

index.html.md

@@ -6,9 +6,13 @@ breadcrumbs: false
 nav: firecracker
 ---
 
+<figure>
+  <img src="/static/images/doc-main.png" alt="Illustration by Annie Ruygt of Frankie the hot air balloon waving to a bird sitting on a hour roof" class="max-w-lg">
+</figure>
+
 <div class="index-page">
 
-## Get started 
+## Get started
 
 Try our [quickstart or demo app](/docs/getting-started/)
 
@@ -105,4 +109,4 @@ _Built-in security and partner extensions._
 
 [Application security by Arcjet](/docs/security/arcjet/) for JavaScript apps
 
-</div>
+</div>

machines/api/index.html.md

@@ -6,6 +6,10 @@ redirect_from: /docs/machines/working-with-machines/
 toc: false
 ---
 
+<figure class="flex justify-center">
+  <img src="/static/images/machine-api.png" alt="Illustration by Annie Ruygt of a group of hovering servers with eyes" class="max-w-lg">
+</figure>
+
 The Fly Machines REST API provides resources to provision and manage Fly Apps, Fly Machines, and Fly Volumes.
 
 

machines/flyctl/fly-machine-run.html.md

@@ -6,6 +6,10 @@ nav: machines
 redirect_from: /docs/machines/run/
 ---
 
+<figure>
+  <img src="/static/images/moto-jump.png" alt="Illustration by Annie Ruygt of a phoenix jumping with a motor bike" class="max-w-lg">
+</figure>
+
 The [`fly machine run`](/docs/flyctl/machine-run/) command is a tool to configure, build, and start a new Machine in one line.
 
 Many, but not all, [Machine configuration](/docs/machines/api-machines-resource/#machine-config-object-properties) options are available to the `fly machine run` command through flags. The available flags are listed in the flyctl help and on the [`fly machine run` reference page](/docs/flyctl/machine-run/).
@@ -39,7 +43,7 @@ Here's the usage of `fly machine run`:
 ```cmd
 fly machine run <image> [command] [flags]
 ```
- 
+
 Here, `<image>` can point to a prebuilt image, or to the current directory (`.`) to build from a Dockerfile.
 
 
@@ -50,17 +54,17 @@ The default behavior of `fly machine run` is to create a new Fly App for the new
 1. Like many flyctl commands, `fly machine run` will pull an app name from a `fly.toml` file if one is present in the working directory. It disregards the rest of the configuration in the file.
 2. If you pass it an app name with `--app <app-name>`, flyctl prefers that name over any name it gets from a `fly.toml`.
 
-If the app name doesn't belong to an existing app in one of your orgs, flyctl asks if you want to create it. 
+If the app name doesn't belong to an existing app in one of your orgs, flyctl asks if you want to create it.
 
  It may be worth creating a `fly.toml` file with just the app name in it, to save using the `--app` option repeatedly. For example:
 
 ```toml
-# a fly.toml just to provide an app name to commands 
+# a fly.toml just to provide an app name to commands
 # run from the same directory
 
 app = my-app-name
 ```
- 
+
 Use `--org <org-name>` to specify which organization a newly created app should belong to. The `--org` flag is ignored when creating the new Machine in an existing app.
 
 ## Name the Machine
@@ -108,12 +112,12 @@ Any source files the Dockerfile uses should be present in the working directory.
 For example:
 
 ```cmd
-fly machine run ghcr.io/livebook-dev/livebook:0.11.4     
+fly machine run ghcr.io/livebook-dev/livebook:0.11.4
 ```
 
 ## Get a shell on a temporary Machine
 
-The following command creates a temporary Machine using the Dockerfile in the working directory, and logs you into an interactive shell on it: 
+The following command creates a temporary Machine using the Dockerfile in the working directory, and logs you into an interactive shell on it:
 
 ```cmd
 fly machine run . --shell
@@ -135,7 +139,7 @@ You can have the Fly.io `init` override the ENTRYPOINT and CMD (if any) of the M
 
 ### Custom CMD
 
-Override CMD by including the command to run at the end of the `fly machine run` invocation. This sets the [`config.init.cmd`](/docs/machines/api-machines-resource/#machine-config-object-properties) property on the Machine. 
+Override CMD by including the command to run at the end of the `fly machine run` invocation. This sets the [`config.init.cmd`](/docs/machines/api-machines-resource/#machine-config-object-properties) property on the Machine.
 
 This example simply spins up a Debian Linux Machine with a `sleep` task to keep it awake; you can shell into it or whatever:
 
@@ -203,18 +207,18 @@ For sensitive environment variables, [set secrets on the app](https://fly.io/doc
 
 The `--port` option defines a network service to allow the Fly Proxy to reach a local service on the Machine. This option gives you access to basic service configuration; the [Machines API](/docs/machines/api-machines-resource/) and [Fly Launch](/docs/launch/) both offer more control over the Machine's [`config.services`](/docs/machines/api-machines-resource/#machine-config-object-properties) properties.
 
-Map any external ports, where the proxy accepts requests directed at the app, to the internal port where the service is listening on IPv4. For each port combination, specify the protocol and [connection handler(s)](/docs/networking/services/#connection-handlers), using this format: 
+Map any external ports, where the proxy accepts requests directed at the app, to the internal port where the service is listening on IPv4. For each port combination, specify the protocol and [connection handler(s)](/docs/networking/services/#connection-handlers), using this format:
 
 ```plain
 port[:machinePort][/protocol[:handler[:handler...]]]
 ```
 
-For example, if your Machine runs a server on port 80, and the Fly Proxy should handle HTTP connections on port 80 and HTTPS connections on port 443, the port configuration would look like this: 
+For example, if your Machine runs a server on port 80, and the Fly Proxy should handle HTTP connections on port 80 and HTTPS connections on port 443, the port configuration would look like this:
 
 ```cmd
 fly machine run . --port 80/tcp:http \
                   --port 443:80/tcp:http:tls \
-                  --app my-app-name      
+                  --app my-app-name
 ```
 
 <div class="important icon">
@@ -284,15 +288,15 @@ The `--volume` flag on the `fly machine run` command sets a subset of the proper
 
 The Fly.io platform uses specific metadata, stored in a Machine's config, for its own purposes, such as assigning Machines to process groups. You can add custom metadata as well.
 
-The following starts a Machine that the `fly deploy` command will try to manage as part of the `app` process group, replacing its image and config with what, if anything, you have set up in the working directory for that app. 
+The following starts a Machine that the `fly deploy` command will try to manage as part of the `app` process group, replacing its image and config with what, if anything, you have set up in the working directory for that app.
 
 ```
 fly machine run . --metadata fly_platform_version=v2 \
                   --metadata fly_process_group=app \
                   --metadata my_metadata=mineallmine
 ```
 
-You can see the [metadata in the Machine config](/docs/machines/api-machines-resource/#machine-config-object-properties): 
+You can see the [metadata in the Machine config](/docs/machines/api-machines-resource/#machine-config-object-properties):
 
 ```cmd
 fly machine status -d -a my-app-name
@@ -317,7 +321,7 @@ The [`files` property](/docs/machines/api-machines-resource/#machine-config-obje
 
 ### Copy a local file into the Machine file system
 
-Use the `--file-local` flag to copy a local file onto the Machine at your specified path: 
+Use the `--file-local` flag to copy a local file onto the Machine at your specified path:
 
 ```
 fly machine run . --file-local /path/inside/machine=local/path
@@ -337,7 +341,7 @@ fly machine run . --file-literal /path/inside/machine="Some text I want in a fil
 In a shell session on the Machine:
 
 ```cmd
-root@2865553aedd268:/# cat /path/inside/machine 
+root@2865553aedd268:/# cat /path/inside/machine
 Some text I want in a file
 ```
 
@@ -380,7 +384,7 @@ Use the `--file-secret` flag when creating the Machine with `fly machine run`. I
 
 ```cmd
 fly machine run . \
-  --file-secret /secret-file=MY_BASE64_SECRET 
+  --file-secret /secret-file=MY_BASE64_SECRET
 ```
 
 The secret is available in the specified file, and not in an environment variable, on that Machine. It's decoded from Base64 into plain text.
@@ -399,13 +403,13 @@ fly secrets set MY_SECRETS="$(base64 < local-secrets)" --stage
 Run a new Machine with the `MY_SECRETS` secret available in a file (`/secret-file`):
 
 ```cmd
-fly machine run ubuntu sleep inf --file-secret /secret-file=MY_SECRETS  
+fly machine run ubuntu sleep inf --file-secret /secret-file=MY_SECRETS
 ```
 
 Check it in a shell session:
 
 ```cmd
-root@d891116b465018:/# cat secret-file 
+root@d891116b465018:/# cat secret-file
 USER="my_name"
 PASSWORD="1a2s3d4f"
 MACARON="macaroon in French"

machines/index.html.md

@@ -4,6 +4,10 @@ layout: docs
 nav: machines
 ---
 
+<figure class="flex justify-center">
+  <img src="/static/images/fly-machines.png" alt="Illustration by Annie Ruygt of a server with legs and arms, walking with a red bird hand-in-hand" class="max-w-lg">
+</figure>
+
 Fly Machines are fast-launching VMs; they can be started and stopped at subsecond speeds. We give you control of your Machine count and each Machine's lifecycle, resources, and region placement with a simple REST API or flyctl commands.
 
 - [**Introduction to Fly Machines**:](/docs/machines/overview/) Learn whether you need low-level Machine control. Find out more about the lifecycle of Fly Machines and about scaling and placement.
@@ -13,7 +17,3 @@ Fly Machines are fast-launching VMs; they can be started and stopped at subsecon
 - **[Run a New Machine](/docs/machines/flyctl/fly-machine-run/) or [Update a Machine](/docs/machines/flyctl/fly-machine-update/) with flyctl:** Configure, build, and start new Machines with a single command or update some or all of a Machine's configuration.
 
 On the other hand, try [Fly Launch](/docs/reference/fly-launch/) if you prefer easy app-wide configuration and containerized deployment for your app.
-
-<figure>
-  <img src="/static/images/docs-machines-fast.webp" alt="fast-launching hot air balloons against a green sky">
-</figure>

security/openid-connect.html.markerb

@@ -5,6 +5,10 @@ nav: firecracker
 redirect_from: /docs/reference/openid-connect/
 ---
 
+<figure>
+  <img src="/static/images/key-hole.png" alt="Illustration by Annie Ruygt of a key hole revealing a pink sky" class="max-w-lg">
+</figure>
+
 Fly Machines sometimes need to access 3rd-party services or cloud providers like AWS, Azure, or GCP. To authenticate against these 3rd parties, your Machines need to supply credentials such as a password or token to the cloud provider; usually these are stored as `fly secrets` and then passed into your Machine's environment variables.
 
 However this approach involves creating hardcoded long-lived credentials on the 3rd party platform and involves either managing a lot of tokens or sharing the same token across multiple apps.
@@ -18,7 +22,7 @@ Adopting OIDC to manage access to 3rd party services allows your apps to easily
 * Granular control over Machines access to 3rd party resources through leveraging the authentication (authN) and authorization (authZ) tools of the 3rd party.
 * Rotating credentials: credentials issued from 3rd parties are only valid for 15 minutes before they expire.
 
-## Understanding OpenID Connect 
+## Understanding OpenID Connect
 
 Every request to the token endpoint generates a unique Json Web Token (JWT). When you give this JWT to a 3rd party they validate the token against the OIDC configuration hosted at the endpoint in the issuer (`iss`) claim. Below is an example of an issued OIDC token. A useful feature here is that the subject (`sub`) claim references the Machine's org name, app name and Machine name. This allows for regex checks to be built against the claim which can restrict accepted tokens to a specific app or Machine.
 
@@ -100,7 +104,7 @@ To read from an S3 bucket using a Fly Machine you'll first need to set up a trus
     ```
 
 1. Create an [IAM Role](https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/roles/create) with the following settings:
- * Trusted Identity: `Web Identity -> Identity Provider -> oidc.fly.io` 
+ * Trusted Identity: `Web Identity -> Identity Provider -> oidc.fly.io`
  * Select the `AmazonS3ReadOnlyAccess` policy.
 
 1. Set the `AWS_ROLE_ARN` as an environment variable in your `fly.toml`.

security/security-at-fly-io.html.md

@@ -4,6 +4,10 @@ layout: docs
 nav: firecracker
 ---
 
+<figure>
+  <img src="/static/images/dark-arts.png" alt="Illustration by Annie Ruygt of a dark magic book with headline Fly Security" class="max-w-lg">
+</figure>
+
 <div class="important icon">
 **Report an issue**: If you have a security concern, or believe you’ve found a vulnerability in any part of our infrastructure, please contact us. You can reach us at [**[email protected]**](mailto:[email protected]), and we can provide you with a Signal number if needed to convey sensitive information.
 </div>