diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 20a8124..609ffdc 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -15,4 +15,6 @@ Anything you think will be useful for reviewers. These aren't hard requirements, just guidelines - [ ] New/modified Rust code formatted with `cargo fmt` +- [ ] Documentation and `README.md` updated for this change, if necessary +- [ ] `CHANGELOG.md` updated for this change diff --git a/CHANGELOG.md b/CHANGELOG.md index 5181e7e..6c96725 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,8 @@ Status: Available for use ### Added - Added Bors support +- Added a navigation section to the documentation (temporary until documentation format is redesigned) +- Added a floki config file for quickly running `hugo` for building and testing documentation ### Fixed - Don't require a floki config file to be present to run `floki completion` diff --git a/README.md b/README.md index f116027..b7a4857 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Suppose we want a build environment based on `alpine:latest` with a C compiler, First create your `Dockerfile`: -``` +```dockerfile FROM alpine:latest RUN apk update && apk add alpine-sdk clang openssh @@ -37,7 +37,7 @@ RUN apk update && apk add alpine-sdk clang openssh and then add a file called `floki.yaml` to the root of your codebase: -``` +```yaml image: build: name: hello-floki @@ -55,8 +55,8 @@ Now run `floki`. You should see the docker container be built, and you will be d It's recommended you add your user to the `docker` group: -``` -sudo usermod -a -G docker USERNAME +```shell +$ sudo usermod -a -G docker USERNAME ``` and logout and in again to pick up the changes. @@ -69,21 +69,21 @@ Precompiled binaries can be downloaded from the releases page (for linux and OSX To obtain `curl` and extract the latest linux binary directly in your shell, run -``` +```shell $ curl -L https://github.com/Metaswitch/floki/releases/download/0.6.1/floki-0.6.1-linux.tar.gz | tar xzvf - ``` You should be able to run `floki` from your working directory: -``` +```shell $ ./floki --version floki 0.6.1 ``` Move it onto your path to run it from anywhere. E.g. -``` -# mv floki /usr/local/bin/ +```shell +$ mv floki /usr/local/bin/ ``` Enjoy! @@ -92,7 +92,7 @@ Enjoy! `floki` can also be installed directly from `cargo`. -``` +```shell $ cargo install floki ``` diff --git a/docs/content/documentation/getting-started.md b/docs/content/documentation/getting-started.md index 9d32c38..13e06f5 100644 --- a/docs/content/documentation/getting-started.md +++ b/docs/content/documentation/getting-started.md @@ -6,30 +6,54 @@ draft: false ## Installation +### Prerequisites + +It's recommended you add your user to the `docker` group: + +```shell +$ sudo usermod -a -G docker USERNAME +``` + +and logout and in again to pick up the changes. + +Alternatively you can run `floki` (after installation) with `sudo -E floki`. + +### Installation from pre-built binaries + Precompiled binaries for linux and OSX can be downloaded from the [releases](https://github.com/Metaswitch/floki/releases) page. For example, to obtain the latest binary with `curl` and extract it, run -``` +```shell $ curl -L https://github.com/Metaswitch/floki/releases/download/0.6.1/floki-0.6.1-linux.tar.gz | tar xzvf - ``` in a shell. You should now be able to run `floki` from your working directory: -``` +```shell $ ./floki --version floki 0.6.1 ``` Copy this into your path to run it without needing to specify the path absolutely. E.g. +```shell +$ mv floki /usr/local/bin/ ``` -# mv floki /usr/local/bin/ + +### Installation from cargo + +`floki` can also be installed directly from `cargo`. + +```shell +$ cargo install floki ``` +### Shell completions + Shell completions can be added to your existing shell session with -``` +```shell source <(floki completion ) ``` @@ -41,7 +65,7 @@ Enjoy! `floki` is configured using a configuration file typically placed in the root of your codebase. As a basic example, write a basic configuration file, and name it `floki.yaml`. -``` +```yaml image: debian:latest init: - echo "Welcome to your first floki container!" @@ -49,13 +73,13 @@ init: Now, in the same directory, run -``` +```shell floki ``` A container will launch with the working directory mounted as your working directory. Verify this by running `ls`: -``` +```shell $ ls ... floki.yaml ... ``` @@ -68,7 +92,7 @@ In general, invoking `floki` in any child directory of this root directory will You can use a different configuration file with `floki` by telling it to use a different file from the command line. For example, if you have another configuration in `config.yaml`, you can run `floki` with -``` +```shell floki -c config.yaml ``` diff --git a/docs/content/intro/feature-overview.md b/docs/content/intro/feature-overview.md index 72bafd9..6c41405 100644 --- a/docs/content/intro/feature-overview.md +++ b/docs/content/intro/feature-overview.md @@ -22,7 +22,7 @@ The ideal workflow is Using a prebuilt image (e.g. one from dockerhub or a docker registry) is as simple as providing its name as a top-level key in `floki.yaml`: -``` +```yaml image: debian:sid ``` @@ -34,7 +34,7 @@ Custom registries can be used by configuring `docker` to use these registries. ` `floki` can use an image built from a `Dockerfile` in source tree. It's easiest to see an example of `floki.yaml` to see how to configure this. -``` +```yaml image: build: name: foo # Will build the image with name foo:floki @@ -44,9 +44,9 @@ image: ``` ## Referencing a key in another yaml file -`floki` can use an image by reference to another yaml file. This can help keep local development environments sync'd with a CI environment. +`floki` can use an image by reference to another yaml file. This can help keep local development environments synced with a CI environment. -``` +```yaml image: yaml: file: .gitlab-ci.yaml @@ -67,7 +67,7 @@ The default shell is `sh`. A shell can be set for a container using the top-level `shell` key: -``` +```yaml image: alpine:latest shell: sh ``` @@ -76,7 +76,7 @@ shell: sh A different shell can be used for initialization and the interactive shell provided to the user. -``` +```yaml image: alpine:latest shell: inner: bash @@ -87,7 +87,7 @@ init: A useful use case here is if you want to run the container with the same user as on the host. `floki` exposes the user id and user group id in environment variables, so you can add a user to the running container and switch to the new user in the inner shell: -``` +```yaml image: foo:latest shell: inner: bash @@ -102,7 +102,7 @@ The commands to make the above work depend on the container you are running. `fl Docker-in-docker (`dind`) can be enabled by setting the top-level `dind` key to `true`. -``` +```yaml image: foo:bar dind: true ``` @@ -111,7 +111,7 @@ Note that the docker CLI tools are still required in the container, and the dock The precise `dind` image can also be set -``` +```yaml dind: image: docker:stable-dind ``` @@ -122,7 +122,7 @@ This helps properly pin and version the docker-in-docker container. `floki` has the ability to use volumes for caching build artifacts between runs of the container (amongst other things). Volumes can be configured in `floki.yaml`: -``` +```yaml volumes: cargo-registry: mount: /home/rust/.cargo/registry @@ -132,7 +132,7 @@ The key names the volume (it can be any valid yaml name), while the `mount` key It's also possible to share volumes across different `floki.yaml`s. For example, you may want to share a `cargo` registry across all Rust build containers. These shared volumes are identified by the name given to the volume. -``` +```yaml volumes: cargo-registry: shared: true @@ -162,7 +162,7 @@ You can set where this directory is mounted in the container using the `mount` k Sometimes it is useful to be able to pull dependencies from source code management servers for builds. To make this easier to do in an automated fashion, `floki` can forward and `ssh-agent` socket into the container, and expose its path through `SSH_AUTH_SOCK`. -``` +```yaml forward_ssh_agent: true ``` @@ -172,7 +172,7 @@ You will need to have an `ssh-agent` running on the host before launching `floki `floki` also allows single commands to be run, rather than dropping into an interactive shell. -``` +```shell $ floki run ls floki.yaml ``` @@ -184,7 +184,7 @@ Note that if you have configured an inner shell, the command will run within the `floki` also allows you to pass additional switches to the underlying docker command, for example to forward port `8080` to the host. -``` +```yaml image: debian:sid docker_switches: - -p diff --git a/docs/content/intro/navigation.md b/docs/content/intro/navigation.md new file mode 100644 index 0000000..97b2cf2 --- /dev/null +++ b/docs/content/intro/navigation.md @@ -0,0 +1,13 @@ +--- +title: "Navigation" +date: 2020-12-21T20:26:44+00:00 +draft: false +# Give heavy weight so that it appears at the top of the documentation homepage +weight: 100 +--- + +For installation, and basic usage, see [getting started]({{< ref "/documentation/getting-started.md" >}} "floki: Getting Started"). + +For an overview of the features of `floki`, see the [feature overview]({{< ref "/intro/feature-overview.md" >}} "floki: Feature Overview"). + +Full documentation can be found [here]({{< ref "/" >}} "floki: Documentation"). diff --git a/floki-hugo.yaml b/floki-hugo.yaml new file mode 100644 index 0000000..a2a2f9f --- /dev/null +++ b/floki-hugo.yaml @@ -0,0 +1,14 @@ +# For shell to work, need Alpine, Debian or Ubuntu versions of this container. +# See https://hub.docker.com/r/klakegg/hugo/. +image: klakegg/hugo:alpine +mount: /src +docker_switches: + # Expose port 1313, as this is the port the server exposes for locally built + # documentation. + - -p + - 1313:1313 +# The entrypoint for this container is a direct call to the "hugo" script. To +# get a shell, we need to pass "shell" to this script, hence the "hack" of +# setting "shell" to "shell". +shell: shell +# To run a hugo server, run "hugo server -D" from the /src/docs directory. diff --git a/src/config.rs b/src/config.rs index d2ed3a1..52c574d 100644 --- a/src/config.rs +++ b/src/config.rs @@ -120,7 +120,7 @@ impl FlokiConfig { .parent() .ok_or_else(|| errors::FlokiInternalError::InternalAssertionFailed { description: format!( - "could not constuct path to external yaml file '{:?}'", + "could not construct path to external yaml file '{:?}'", &yaml.file ), })? diff --git a/src/errors.rs b/src/errors.rs index 165e051..a996953 100644 --- a/src/errors.rs +++ b/src/errors.rs @@ -52,7 +52,7 @@ pub enum FlokiError { exit_status: FlokiSubprocessExitStatus, }, - #[fail(display = "Failed to check existance of image '{}': {}", image, error)] + #[fail(display = "Failed to check existence of image '{}': {}", image, error)] FailedToCheckForImage { image: String, error: io::Error }, #[fail(display = "Failed to find the key '{}' in file '{}'", key, file)]