Skip to content
This repository was archived by the owner on Apr 28, 2020. It is now read-only.

Commit 9d5f88f

Browse files
ammarionhooyr
ammario
authored and
nhooyr
committed
Write out initial version of docs
- Establishes structure in Hugo - Removes redundant information from README, redirecting to the central docs instead. These docs are by no means ready to publish, but serve as a base for future work.
1 parent 9044b44 commit 9d5f88f

File tree

21 files changed

+419
-142
lines changed

21 files changed

+419
-142
lines changed

‎README.md

Lines changed: 3 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -29,127 +29,11 @@ sail run codercom/sail
2929
# installs code-server in it, and creates a browser.
3030
```
3131

32-
## Projects
32+
## Documentation
3333

34-
sail enforces that projects are stored on the host filesystem at `$project_root/<org>/<repo>`.
34+
Documentation is available in markdown form at [site/content/docs.](site/content/docs)
3535

36-
`$project_root` is a configuration variable.
37-
38-
Projects are stored in the container at `~/<repo>`.
39-
40-
To enable some special-case languages such as Go, the project root can be configured
41-
via the project_root label. For example:
42-
43-
```Dockerfile
44-
LABEL project_root "~/go/src/"
45-
```
46-
47-
Projects are bind-mounted into the container, so deleting a container does not delete project files
48-
and you can seamlessly interact with project files outside of the container.
49-
50-
## Environments
51-
52-
### Project-defined environment
53-
54-
Projects can define their own environment by specifying a `.sail/Dockerfile` file.
55-
56-
The dev container must have `codercom/ubuntu-dev` as a parent.
57-
58-
The build will occur in the repo's root directory.
59-
60-
### Permissions
61-
62-
The user that creates the container has their Uid mapped to the `user` user within the container.
63-
64-
This ensures that newly created project files have the correct permissions on
65-
the host.
66-
67-
### Live modification
68-
69-
The sail workflow promotes a unique environment for each project, with common
70-
configurations explicitely declared.
71-
72-
The workflow for modifying an environment goes like:
73-
74-
1) Have code-server open in some window.
75-
1) Have a terminal open.
76-
1) Call `sail edit someorg/project`
77-
1) Optionally, call `sail edit -hat someorg/project` to just modify the hat.
78-
1) Edit the file in the editor that pops up.
79-
1) Save
80-
1) code-server window reloads with changed environment.
81-
82-
sail will listen for changes to the file being edited, and will magically
83-
recreate the environment as changes are made (assuming those changes make
84-
sense).
85-
86-
To make iterations seamless:
87-
88-
1) Docker caching is heavily employed.
89-
1) `code-server` automatically reloads the page when the new environment is
90-
created.
91-
1) As usual, the project folder is persisted so no changes are lost.
92-
1) UI state is persisted so the exact layout of your tabs in undisturbed.
93-
94-
## Hats
95-
96-
A _hat_ is a build directory with a Dockerfile which has it's `FROM` clause
97-
replaced with the repository-provided image. Essentially, hats let you
98-
personalize your development environment.
99-
100-
For example:
101-
102-
```Dockerfile
103-
FROM ubuntu-dev
104-
RUN sudo apt install fish
105-
RUN chsh user -s $(which fish)
106-
```
107-
108-
is a hat that would install fish, and configure it as the default
109-
shell regardless of which shell the repository-provided image uses.
110-
111-
The `FROM ubuntu-dev` will be replaced with `FROM <repo_image>` when sail
112-
assembles your dev container.
113-
114-
---
115-
116-
`sail` promotes the use of Ubuntu/apt-based dev containers so that hats are
117-
reliable.
118-
119-
You can only wear a single hat at a time.
120-
121-
### GitHub
122-
123-
To enable expirementation, hats can be used from github like so:
124-
125-
`-hat github:ammario/dotfiles`
126-
127-
---
128-
129-
Hats are supposed to enable global personalization, so GitHub hats should just be used for expirementation.
130-
131-
## Shares
132-
133-
Projects and hats can specify shares using Docker labels of form
134-
`share.<share_name>="host_path:guest_path"`.
135-
136-
For example,
137-
138-
```Dockerfile
139-
LABEL share.go_mod="~/go/pkg/mod:/root/go/pkg/mod"
140-
```
141-
142-
Shares the host's Go mod cache with the guest.
143-
144-
## Configuration
145-
146-
A self-documenting configuration is stored at `~/.config/sail/sail.toml`
147-
148-
Checkout `defaultconfig.go` for the default config.
149-
150-
## Workflow Tips
151-
152-
Checkout `workflow/` for useful snippets.
36+
Or, you can find it at [https://sail.dev/docs](https://sail.dev/docs)
15337

15438
## Future
15539

‎go.mod

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,13 @@ require (
1515
github.com/google/go-cmp v0.2.0 // indirect
1616
github.com/google/go-github/v24 v24.0.1
1717
github.com/gorilla/mux v1.7.1 // indirect
18+
github.com/mattn/go-isatty v0.0.7 // indirect
1819
github.com/morikuni/aec v0.0.0-20170113033406-39771216ff4c // indirect
1920
github.com/opencontainers/go-digest v1.0.0-rc1 // indirect
2021
github.com/opencontainers/image-spec v1.0.1 // indirect
2122
github.com/pkg/browser v0.0.0-20180916011732-0a3d74bf9ce4
2223
github.com/pkg/errors v0.8.1 // indirect
2324
github.com/sirupsen/logrus v1.4.1 // indirect
24-
github.com/skratchdot/open-golang v0.0.0-20190331143844-1a48294fa5dd // indirect
2525
github.com/stretchr/testify v1.3.0
2626
go.coder.com/flog v0.0.0-20190129195112-eaed154a0db8
2727
golang.org/x/sys v0.0.0-20190415145633-3fd5a3612ccd // indirect

‎go.sum

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,8 @@ github.com/mattn/go-colorable v0.0.9 h1:UVL0vNpWh04HeJXV0KLcaT7r06gOH2l4OW6ddYRU
4848
github.com/mattn/go-colorable v0.0.9/go.mod h1:9vuHe8Xs5qXnSaW/c/ABM9alt+Vo+STaOChaDxuIBZU=
4949
github.com/mattn/go-isatty v0.0.4 h1:bnP0vzxcAdeI1zdubAl5PjU6zsERjGZb7raWodagDYs=
5050
github.com/mattn/go-isatty v0.0.4/go.mod h1:M+lRXTBqGeGNdLjl/ufCoiOlB5xdOkqRJdNxMWT7Zi4=
51+
github.com/mattn/go-isatty v0.0.7 h1:UvyT9uN+3r7yLEYSlJsbQGdsaB/a0DlgWP3pql6iwOc=
52+
github.com/mattn/go-isatty v0.0.7/go.mod h1:Iq45c/XA43vh69/j3iqttzPXn0bhXyGjM0Hdxcsrc5s=
5153
github.com/morikuni/aec v0.0.0-20170113033406-39771216ff4c h1:nXxl5PrvVm2L/wCy8dQu6DMTwH4oIuGN8GJDAlqDdVE=
5254
github.com/morikuni/aec v0.0.0-20170113033406-39771216ff4c/go.mod h1:BbKIizmSmc5MMPqRYbxO4ZU0S0+P200+tUnFx7PXmsc=
5355
github.com/opencontainers/go-digest v1.0.0-rc1 h1:WzifXhOVOEOuFYOJAW6aQqW0TooG2iki3E3Ii+WN7gQ=
@@ -85,8 +87,10 @@ golang.org/x/sys v0.0.0-20180824143301-4910a1d54f87/go.mod h1:STP8DvDyc/dI5b8T5h
8587
golang.org/x/sys v0.0.0-20180905080454-ebe1bf3edb33/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
8688
golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a h1:1BGLXjeY4akVXGgbC9HugT3Jv3hCI0z56oJR5vAMgBU=
8789
golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
90+
golang.org/x/sys v0.0.0-20190222072716-a9d3bda3a223/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
8891
golang.org/x/sys v0.0.0-20190415145633-3fd5a3612ccd h1:MNN7PRW7zYXd8upVO5qfKeOnQG74ivRNv7sz4k4cQMs=
8992
golang.org/x/sys v0.0.0-20190415145633-3fd5a3612ccd/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
93+
golang.org/x/text v0.3.0 h1:g61tztE5qeGQ89tm6NTjjM9VPIm088od1l6aSorWRWg=
9094
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
9195
golang.org/x/time v0.0.0-20190308202827-9d24e82272b4 h1:SvFZT6jyqRaOeXpc5h/JSfZenJ2O330aBsf7JfSUXmQ=
9296
golang.org/x/time v0.0.0-20190308202827-9d24e82272b4/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=

‎site/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
11
resources
2+
public

‎site/content/docs/_index.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
2+
+++
3+
+++

‎site/content/docs/commands/edit.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
+++
2+
type="doc"
3+
title="edit"
4+
browser_title="Sail - Commands - edit"
5+
+++
6+
7+
```
8+
NAME:
9+
sail edit - edit your environment in real-time.
10+
11+
USAGE:
12+
sail edit [flags] <repo>
13+
14+
DESCRIPTION:
15+
This command allows you to edit your project's environment while it's running.
16+
Depending on what flags are set, the Dockerfile you want to change will be opened in your default
17+
editor which can be set using the "EDITOR" environment variable. Once your changes are complete
18+
and the editor is closed, the environment will be rebuilt and rerun with minimal downtime.
19+
20+
If no flags are set, this will open your project's Dockerfile. If the -hat flag is set, this
21+
will open the hat Dockerfile associated with your running project in the editor. If the -new-hat
22+
flag is set, the project will be adjusted to use the new hat.
23+
24+
Flags:
25+
-hat Edit the hat associated with this project. (false)
26+
-new-hat Path to new hat.
27+
```
28+
29+
The `edit` command lets you edit your environment.
30+
31+
## Workflow
32+
33+
The workflow for modifying an environment goes like:
34+
35+
1. Have Sail open in some window.
36+
1. Have a host terminal open.
37+
1. Call `sail edit someorg/project`
38+
1. Optionally, call `sail edit -hat someorg/project` to just modify the hat.
39+
1. Edit the file in the editor that pops up.
40+
1. Save
41+
1. code-server window reloads with changed environment.
42+
43+
Iteration is seamless because
44+
45+
1. Docker caches most of the commands.
46+
1. `code-server` automatically reconnects the page when the new environment is
47+
created.
48+
1. The project folder is always persisted so WIP changes are safe.
49+
1. UI state is persisted so the exact layout of your editor in undisturbed.

‎site/content/docs/commands/ls.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
+++
2+
type="doc"
3+
title="ls"
4+
browser_title="Sail - Commands - ls"
5+
+++
6+
7+
```
8+
NAME:
9+
sail ls - Lists all sail containers.
10+
11+
USAGE:
12+
sail ls
13+
14+
DESCRIPTION:
15+
Queries docker for all containers with the com.coder.sail label.
16+
17+
Flags:
18+
-all Show stopped container. (false)
19+
```
20+
21+
The `ls` command lists all containers with Sail Docker labels.
22+
23+
Example output:
24+
25+
```
26+
name hat url status
27+
codercom/sail http://127.0.0.1:8828
28+
codercom/sshcode http://127.0.0.1:8130
29+
codercom/m http://127.0.0.1:8754
30+
codercom/code-server http://127.0.0.1:8828
31+
codercom/sail-tmp-kEG58 http://127.0.0.1:8130
32+
```

‎site/content/docs/commands/run.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
+++
2+
type="doc"
3+
title="run"
4+
browser_title="Sail - Commands - run"
5+
+++
6+
7+
```
8+
NAME:
9+
sail run - Runs a project container.
10+
11+
USAGE:
12+
sail run [flags] <project>
13+
14+
DESCRIPTION:
15+
This command is used for opening and running a project.
16+
If a project is not yet created or running with the name,
17+
one will be created and a new editor will be opened.
18+
If a project is already up and running, this won't
19+
start a new container, but instead will reuse the
20+
already running container and open a new editor.
21+
22+
Flags:
23+
-hat Custom hat to use.
24+
-image Custom docker image to use.
25+
-keep Keep container when it fails to build. (false)
26+
-test-cmd A command to use in-place of starting code-server for testing purposes.
27+
```
28+
29+
The `run` command starts up a container, and plops you into code-server.
30+
31+
## Browser
32+
33+
Chrome is always used if it is available, because we can open it in `--app` mode,
34+
which makes the code-server interface feel exactly live native VS Code.
35+
36+
If Chrome isn't available, we open the URL in the OS's default browser.

‎site/content/docs/commands/shell.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
+++
2+
type="doc"
3+
title="shell"
4+
browser_title="Sail - Commands - shell"
5+
+++
6+
7+
```
8+
NAME:
9+
sail shell - shell drops you into the default shell of a repo container.
10+
11+
USAGE:
12+
sail shell <repo>
13+
14+
DESCRIPTION:
15+
shell drops you into the default shell of a repo container.
16+
```
17+
18+
The `shell` command drops you into the container's shell on the host.

‎site/content/docs/concepts/config.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
+++
2+
type="doc"
3+
title="Configuration"
4+
browser_title="Sail - Docs - Configuration"
5+
+++
6+
7+
Sail is about moving configuration into controlled projects and hats, so naturally
8+
it strives to keep it's configuration minimal. Sail accepts a variety of flags
9+
through it's commands, but there is a little bit global configuration at
10+
11+
`~/.config/sail/sail.toml`.
12+
13+
The self-documenting default configuration for convenience:
14+
15+
```toml
16+
# default_image is the default Docker image to use if the repository provides none.
17+
default_image = "codercom/ubuntu-dev"
18+
19+
# project_root is the base from which projects are mounted.
20+
# projects are stored in directories with form "<root>/<org>/<repo."
21+
project_root = "~/Projects"
22+
23+
# default hat lets you configure a hat that's applied automatically by default.
24+
# default_hat = ""
25+
```

0 commit comments

Comments
 (0)