Disperse "Working with fly apps" content (superfly#1114)

* disperse working with fly apps content

* feedback

apps/custom-domain.html.markerb

@@ -0,0 +1,83 @@
+---
+title: Use a custom domain 
+layout: docs
+nav: firecracker
+order: 35
+---
+
+When you create a Fly App, it is automatically given a `fly.dev` sub-domain, based on the app's name. This is great for testing, but when you want to go to full production you'll want your application to appear on your own domain and have HTTPS set up for you as it is with your `.fly.dev` domain. That's where the `fly certs` command comes in. But let's step back before we set up the TLS certificate, to the first step: directing traffic to your site.
+
+## Set a CNAME record
+
+The simplest option for directing traffic to your site is to create a CNAME record for your custom domain that points at your `.fly.dev` host. For example, if you have a custom domain called `example.com` and an app called `exemplum`, then you can create a CNAME record for `example.com`'s DNS that would look like:
+
+```
+CNAME @ exemplum.fly.dev
+```
+
+You'll need to configure this with your DNS provider. 
+
+Now, accessing `example.com` will tell the DNS system to look up `exemplum.fly.dev` and return its results. 
+
+## Set the A record
+
+The other option is slightly more complicated because it uses the IP address of the app, rather than its DNS name. The upside is that it is slightly faster.
+
+To start, you need the Fly IP address of your deployed application. To get that, use the `fly ips list` command.
+
+You'll need to configure the A record with your DNS provider. You need to add in an "A Record" for your domain that points to the IP address. Once this is done and propagated through the DNS system, you should be able to connect over unencrypted HTTP to using the domain name. Continuing the preceding example, that's the domain name: `http://example.com`.
+
+## Get certified
+
+To enable HTTPS on the domain, you need to get a certificate. Fly.io does that for you automatically.
+
+It starts with creating a certificate for your custom domain with the `fly certs add` command. For example:
+
+```cmd
+fly certs add example.com
+```
+```output
+  Hostname                    = example.com
+  Configured                  = true
+  Issued                      =
+  Certificate Authority       = lets_encrypt
+  DNS Provider                = enom
+  DNS Validation Instructions =
+  DNS Validation Hostname     =
+  DNS Validation Target       = example.com.5xzw.flydns.net
+  Source                      = fly
+  Created At                  = 0001-01-01T00:00:00Z
+  Status                      =
+```
+
+Running `fly certs add` starts the process of getting a certificate. 
+
+Run `fly certs show` to get the details needed for your next step. For example:
+
+```cmd
+fly certs show example.com
+```
+```output
+  Hostname                    = example.com
+  Configured                  = true
+  Issued                      = ecdsa, rsa
+  Certificate Authority       = lets_encrypt
+  DNS Provider                = enom
+  DNS Validation Instructions = CNAME _acme-challenge.example.com => example.com.5xzw.flydns.net.
+  DNS Validation Hostname     = _acme-challenge.example.com
+  DNS Validation Target       = example.com.5xzw.flydns.net
+  Source                      = fly
+  Created At                  = 1m24s ago
+  Status                      = Ready
+```
+
+The **DNS Validation Instructions** are an optional next step. For a short time (minutes) after we start the process of generating
+the first-ever certificate for your site, trying to load that site with an HTTPS URL will generate errors. If you'd like to make sure
+those errors aren't ever visible, you can use a DNS challenge to pre-generate the certificate. 
+
+To do that, you need to create a `CNAME` DNS record for a subdomain, `_acme-challenge`, of your domain (the DNS Validation host name)
+and point it at the DNS Validation Target. The process will depend on your DNS provider. Once complete, and the updated DNS data has propagated, that domain will be queried and confirm you have control of it. Certificates will be generated and installed and you'll be able to access your custom domain.
+
+## Related topics
+
+For a more detailed example of configuring custom domains, see the [Custom domains and SSL certificates](/docs/app-guides/custom-domains-with-fly/) guide.

laravel/the-basics/post-deployment.html.md

@@ -45,11 +45,11 @@ By default, Fly.io updates Laravel's logging channel to `"stderr"` through the `
   LOG_LEVEL = "info"
   LOG_STDERR_FORMATTER = "Monolog\\Formatter\\JsonFormatter"
 ```
-This `"stderr"` configuration prints your application logs into the console, where the [Fly.io service](/docs/getting-started/working-with-fly-apps/#viewing-logs) is able to listen and capture logs from. 
+This `"stderr"` configuration prints your application logs into the console, where the Fly.io service is able to listen and capture logs from. 
 
 In order to **view your logs** captured by the Fly.io service, you can either:
 
-1. Visit your application's monitoring section from your Fly.io dashboard likeso: `"https://fly.io/apps/<app-name>/monitoring"`
+1. Visit your application's monitoring section from your Fly.io dashboard like so: `"https://fly.io/apps/<app-name>/monitoring"`
 2. Or run the [flyctl logs](/docs/flyctl/logs/) command:
 
 ```cmd

partials/_firecracker_nav.html.erb

@@ -8,9 +8,6 @@
       <li>
         <%= nav_link "Hands-on with Fly.io", "/docs/hands-on/" %>
       </li>
-      <li>
-        <%= nav_link "Working with Fly Apps", "/docs/getting-started/working-with-fly-apps/" %>
-      </li>
       <li>
         <%= nav_link "Troubleshooting Deployments", "/docs/getting-started/troubleshooting/" %>
       </li>
@@ -58,6 +55,9 @@
       <li>
         <%= nav_link "Get Information about an App", "/docs/apps/info/" %>
       </li>
+      <li>
+        <%= nav_link "Use a Custom Domain", "/docs/apps/custom-domain/" %>
+      </li>
       <li>
         <%= nav_link "Scale Machine CPU and RAM", "/docs/apps/scale-machine/" %>
       </li>

reference/secrets.html.markerb

@@ -15,37 +15,36 @@ Secrets are stored in an encrypted vault. When you set a secret through flyctl,
 
 When we launch a Machine for your app, we issue a temporary auth token to the host it runs on. The Fly.io agent on the host uses this token to decrypt your app secrets and inject them into your Machine as environment variables at boot time. When you destroy your Machines, the host environment no longer has access to your app secrets.
 
-<section class="warning">`flyctl` and our API servers are designed to prevent user secrets from being extracted. However, secrets are available to your application code as environment variables. People with deploy access _can_ deploy code that reads secret values and prints them to logs, or writes them to unencrypted data stores.</section>
+<section class="warning icon">
+**Warning:** `flyctl` and our API servers are designed to prevent user secrets from being extracted. However, secrets are available to your application code as environment variables. People with deploy access _can_ deploy code that reads secret values and prints them to logs, or writes them to unencrypted data stores.
+</section>
 
-## Setting secrets
+## Set secrets
 
 The `fly secrets set` command sets one or more app secrets, then updates each Machine belonging to that Fly App. This involves a restart of the Machine and a consequent reset of its ephemeral file system.
 
-<%= partial "docs/partials/set_secrets" %>
+The following example sets a secret that's available as the `DATABASE_URL` environment variable within your application processes:
 
-In the above example, the secret is avaliable as the `DATABASE_URL` environment variable within your application processes.
+<%= partial "docs/partials/set_secrets" %>
 
-To set, or update, a secret in the app's vault, but defer updating the Machines to later, use the `--stage` option:
+To set, or update, a secret in the app's vault, but defer updating the Machines to later, use the `--stage` option. For example:
 
 ```cmd
 fly secrets set DATABASE_URL=postgres://example.com/mydb --stage
 ```
 
-In this case, the staged secret will be available only on Machines that are started or updated after the `fly secrets set` command was run.
+In the preceding example, the staged secret will be available only on Machines that are started or updated after the `fly secrets set` command was run.
 
-<section class="warning icon">
-You can update a machine by triggering a new release with `fly deploy`. Alternatively, the `fly secrets deploy` command will redeploy the current release with the
-staged secrets. This is helpful if you want to skip rebuilding the image from source code.</section>
+The `secrets` command can also take secrets from STDIN. For commands and options, see the [`fly secrets` docs](/docs/flyctl/secrets/) or run `fly secrets --help`.
 
-## Removing secrets
+<section class="note icon">
+**Note:** You can update a machine by triggering a new release with `fly deploy`. Alternatively, the `fly secrets deploy` command will redeploy the current release with the staged secrets. This is helpful if you want to skip rebuilding the image from source code.</section>
 
-The `fly secrets unset` command clears one or more secret values.
+## List secrets
 
-```cmd
-fly secrets unset MY_SECRET DATABASE_URL
-```
+List secrets that are set for your app. The list shows only the secret name; the value is not shown as it is a secret.
 
-## Listing secrets
+For example:
 
 ```cmd
 fly secrets list
@@ -58,3 +57,13 @@ fly secrets list
 ```
 
 For security reasons, we do not allow read access to the plain-text values of secrets.
+
+## Remove secrets
+
+Remove one or more secret values from your app by name.
+
+The following example removes two secrets from the app:
+
+```cmd
+fly secrets unset MY_SECRET DATABASE_URL
+```