Add more docs

Author: Nathan Potter

.sail/Dockerfile

@@ -1,6 +1,11 @@
 FROM codercom/ubuntu-dev-go
-RUN sudo apt-get install -y htop hugo
+RUN sudo apt-get install -y htop
 LABEL project_root "~/go/src/go.coder.com"
 
 # Modules break much of Go's tooling.
 ENV GO111MODULE=off
+
+# Install the latest version of Hugo.
+RUN wget -O /tmp/hugo.deb https://github.com/gohugoio/hugo/releases/download/v0.55.4/hugo_extended_0.55.4_Linux-64bit.deb && \
+    sudo dpkg -i /tmp/hugo.deb && \
+    rm -f /tmp/hugo.deb

site/config.toml

@@ -1,6 +1,6 @@
 theme = "sail"
 languageCode = "en-us"
 defaultContentLanguage="en"
-title = "My New Hugo Site"
+title = "Sail"
 
-sectionPagesMenu = "main"
+sectionPagesMenu = "main"

site/content/docs/_index.md

@@ -1,3 +1,4 @@
 
 +++
+title="Introduction"
 +++

site/content/docs/commands/edit.md

@@ -2,6 +2,7 @@
 type="docs"
 title="edit"
 browser_title="Sail - Commands - edit"
+section_order=1
 +++
 
 ```
@@ -46,4 +47,4 @@ Iteration is seamless because
 1. `code-server` automatically reconnects the page when the new environment is
 created.
 1. The project folder is always persisted so WIP changes are safe.
-1. UI state is persisted so the exact layout of your editor in undisturbed.
+1. UI state is persisted so the exact layout of your editor is undisturbed.

site/content/docs/commands/ls.md

@@ -2,6 +2,7 @@
 type="docs"
 title="ls"
 browser_title="Sail - Commands - ls"
+section_order=2
 +++
 
 ```

site/content/docs/commands/rm.md

@@ -0,0 +1,23 @@
++++
+type="docs"
+title="rm"
+browser_title="Sail - Commands - rm"
+section_order=3
++++
+
+```
+NAME:
+	sail rm - Remove a sail container from the system.
+
+USAGE:
+	sail rm [flags] <repo>
+
+DESCRIPTION:
+	This command allows for removing a single container
+	or all of the containers on a system with the -all flag.
+
+Flags:
+	-all	Remove all sail containers.	(false)
+```
+
+The `rm` command lets you remove sail environments from your system.

site/content/docs/commands/run.md

@@ -2,6 +2,7 @@
 type="docs"
 title="run"
 browser_title="Sail - Commands - run"
+section_order=0
 +++
 
 ```
@@ -26,11 +27,12 @@ Flags:
 	-test-cmd	A command to use in-place of starting code-server for testing purposes.
 ```
 
-The `run` command starts up a container, and plops you into code-server.
+The `run` command starts up a container, and opens a browser window pointing to
+the project's running code-server.
 
 ## Browser
 
-Chrome is always used if it is available, because we can open it in `--app` mode,
-which makes the code-server interface feel exactly live native VS Code.
+Chrome is always used if it is available, because sail can open it in `--app` mode,
+which makes the code-server interface feel exactly like native VS Code.
 
-If Chrome isn't available, we open the URL in the OS's default browser.
+If Chrome isn't available, sail opens the URL in the OS's default browser.

site/content/docs/commands/shell.md

@@ -2,6 +2,7 @@
 type="docs"
 title="shell"
 browser_title="Sail - Commands - shell"
+section_order=4
 +++
 
 ```
@@ -15,4 +16,4 @@ DESCRIPTION:
 	shell drops you into the default shell of a repo container.
 ```
 
-The `shell` command drops you into the container's shell on the host.
+The `shell` command drops you into the container's shell on the host.

site/content/docs/concepts/config.md

@@ -2,15 +2,16 @@
 type="docs"
 title="Configuration"
 browser_title="Sail - Docs - Configuration"
+section_order=5
 +++
 
 Sail is about moving configuration into controlled projects and hats, so naturally
 it strives to keep it's configuration minimal. Sail accepts a variety of flags
-through it's commands, but there is a little bit global configuration at
+through it's commands, but there is a little bit of global configuration located at:
 
 `~/.config/sail/sail.toml`.
 
-The self-documenting default configuration for convenience:
+Here is the default self-documenting configuration for reference:
 
 ```toml
 # default_image is the default Docker image to use if the repository provides none.
@@ -22,4 +23,4 @@ project_root = "~/Projects"
 
 # default hat lets you configure a hat that's applied automatically by default.
 # default_hat = ""
-```
+```

site/content/docs/concepts/docker.md

@@ -1,76 +1,66 @@
-
 +++
 type="docs"
 title="Docker"
 browser_title="Sail - Docs - Docker"
-draft=true
+section_order=4
 +++
 
 Sail can be thought of as a wrapper around the Docker toolchain, focused
 on managing development environments.
 
 It stores most of it's state in the Docker daemon
-in the form of metadata and labels.
-
-Informational Sail Docker labels begin with `com.coder.sail`.
-
-## Command labels
+in the form of metadata and [labels](/docs/concepts/labels).
 
-Sail artificially extends the Dockerfile syntax through labels.
 
-For example:
-
-```Dockerfile
-LABEL project_root "~/go/src"
-```
+## Immutability
 
-Will instruct Sail to use `~/go/src` as the project root.
+Sail tries to encourage a workflow of explicitly describing your development environment in a way
+that's easy to share and iterate on.
 
-We call these kinds of labels _command labels_. Each command label is introduced
-throughout these docs.
+If you want to make a change to the environment, you should modify your [hat](/docs/concepts/hats) or the [project's](/docs/concepts/projects)
+Dockerfile.
 
-## Container Naming
-
-Containers are named `<org>-<project>` in Docker, but `<org>/project` in Sail.
-
-## Networking
+## Project Defined Environment
 
-### MacOS
+Projects can define their own environment by specifying a `.sail/Dockerfile` file.
+If a `.sail/Dockerfile` is not present in a repository, the `codercom/ubuntu-dev`
+image will be used as the base environment.
 
-On MacOS hosts, the Docker container is given a bridge network.
+When specifying a custom project environment, the dev container must have
+be an ancestor of `codercom/ubuntu-dev` in order to have the proper dependencies
+setup.
 
-### Linux
+When building the project's image, the build will be rooted in the project's root,
+essentially calling this docker build command:
 
-To keep workflow as close to local development as possible, we give
-the container the host network. That means if your webserver within Sail binds
-to `:8080`, `127.0.0.1:8080` on the host will work just fine.
+```bash
+ docker build --network=host -f $project_root/<org>/<repo>/.sail/Dockerfile $project_root/<org>/<repo>
+```
 
+## Container Permissions
 
-## Dockerfile Best Practices
+The current user on the host is mapped to the user named `user` within
+the development environment.  That means files permissioned to `user` within
+the container, will appear to have the same set of permissions for your user on the host.
 
-[Official Dockerfile best practices.](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)
 
----
+Sail uses `user` and not `root` within the container because:
 
-Maximize layer caching by seperating command as much as possible:
+- A lot of tools will complain about being root.
+- Most developers are used to being non-root and the `sudo` workflow.
 
-**Bad**
-```
-RUN sudo apt install -y htop dstat dog
-```
+## Container Naming
 
-**Good**
-```
-RUN sudo apt install -y htop
-RUN sudo apt install -y dstat
-RUN sudo apt install -y dog
-```
+Containers are named `<org>_<project>` in Docker, but `<org>/project` in Sail.
 
-As you become aware of what installations the project _always_ needs, we're
-better off merging the commands and moving them to the beginning of the Dockerfile.
+## Networking
 
-**Tip**: whenever changing or adding a command, always do it at the bottom of
-the Dockerfile. The Dockerfile will approach it's layer-optimized version.
+To keep workflow as close to local development as possible, sail uses docker
+host networking. That means if your webserver within Sail binds
+to `:8080`, it will be accessible from `127.0.0.1:8080` in your browser.
 
+## Dockerfile Best Practices
 
----
+[Dockerfile best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) 
+for a reference on how to properly structure and write your [project](/docs/concepts/projects) and [hat](/docs/concepts/hats)
+Dockerfiles.

site/content/docs/concepts/hats.md

@@ -2,25 +2,31 @@
 type="docs"
 title="Hats"
 browser_title="Sail - Docs - Hats"
+section_order=3
 +++
 
-A _hat_ is a build directory with a Dockerfile which has it's `FROM` clause
-replaced with the repository-provided image. Essentially, hats let you
-personalize your development environment.
+A _hat_ is a build directory with a Dockerfile that allows you to extend
+every project environment with your own personalization. Hats allow you to
+bring your own tooling, configuration, and workflow into every Sail project
+you work on.
+
+In order for Sail to extend the project's environment, the hat Dockerfile's
+`FROM` clause is replaced with the repository-provided image.
 
 For example:
 
 ```Dockerfile
-FROM ubuntu-dev
+FROM ubuntu
+
 RUN sudo apt install fish
 RUN chsh user -s $(which fish)
 ```
 
 is a hat that would install fish, and configure it as the default
 shell regardless of which shell the repository-provided image uses.
 
-The `FROM ubuntu-dev` will be replaced with `FROM <repo_image>` when sail
-assembles your dev container.
+The `FROM ubuntu` will be replaced with `FROM <repo_image>` when sail
+assembles your dev container in order to extend the project's environment.
 
 ---
 
@@ -37,4 +43,4 @@ To enable expirementation, hats can be used from github like so:
 
 ---
 
-Hats enable personalization, so **GitHub hats should just be used for expirementation.**
+Hats enable personalization, so **GitHub hats should just be used for experimentation.**

site/content/docs/concepts/immutability.md

@@ -0,0 +1,69 @@
++++
+type="docs"
+title="Labels"
+browser_title="Sail - Docs - Labels"
+section_order=1
++++
+
+Sail makes extensive use of Docker labels to maintain state and to allow users to fully configure
+their project environments.
+
+## Configuration Labels
+
+### Project Root Label
+
+As described in [projects](/docs/concepts/projects), the bind mount target of the project's root can be specified
+using the `project_root` label. By default the project root is bind mounted to `~/<repo>` inside of
+the container.
+
+For example:
+
+```Dockerfile
+LABEL project_root "~/go/src/"
+```
+
+Will bind mount the host directory `$project_root/<org>/<repo>` to `~/go/src/<repo>` in the container.
+
+
+### Share Labels
+
+A sail share is a directory on the host that you want shared with your
+sail container. Any shares that are specified within the Project or hat
+Dockerfiles will be bind mounted to the proper location inside of the
+container.
+
+Projects and hats can specify shares using command labels of the form:
+
+`share.<share_name>="host_path:guest_path"`.
+
+For example, if you wanted to share your go mod cache with your container
+you would add this to your project or hat Dockerfile:
+
+```Dockerfile
+LABEL share.go_mod="~/go/pkg/mod:~/go/pkg/mod"
+```
+
+---
+
+Shares are recommended for
+
+- Filesystem-level caches
+    - Go mod cache
+    - Yarn cache
+- User-specific configuration
+    - VS Code configuration (auto)
+    - SSH keys
+    - gitconfig
+- Working data
+    - Project files (auto)
+    - Data analysis results
+
+It's important to keep in mind that shares can easily undermine the
+reproducibility and consistency of your environments. Be careful with blanket shares
+such as `~:~` which introduce variance.
+
+## State Labels
+
+Sail uses Docker labels that begin with `com.coder.sail` to manage any state
+that the CLI may need. These labels are only required by the Sail CLI and aren't
+useful for user configuration.