Move all of the docs to mkdocs
--- a/README.md Thu Dec 23 17:12:45 2021 -0600
+++ b/README.md Sat Mar 26 06:27:05 2022 -0500
@@ -1,132 +1,29 @@
+[  ](https://issues.imfreedom.org/issues/CONVEY?u=1) Convey is a pipeline for running containers and protecting the host as much as
possible. It accomplishes this goal by creating a volume and making it
available to each item in the pipeline.
-Convey was created out of the need to build [Pidgin](https://pidgin.im) and its-supporting libraries on multiple Linux distributions, Windows and MacOS. While-there are many continuous integration tools out there, all of them still-require maintenance and can only be used by the project itself.-This becomes a problem when you have a community of plugin developers who would-also like to build against all of its supported operating systems but can't and-shouldn't need to put forth the effort and maintenance involved with using-This is where Convey's concept of [build containers](#markdown-header-concepts)-comes into use. Once you have all the dependencies required to build something,-like a Pidgin plugin, you are then able to share that container image with-everyone using this system and they are then able to use that image to build-against. So a project like Pidgin can supply build images containing the most-recent releases with all of the build dependencies for multiple platforms and-then plugin developers can use that image to test their plugins against.+Full documentation is available at +[docs.imfreedom.org/convey](https://docs.imfreedom.org/convey/). -If you still have doubts about how Convey can simplify your workflow and-increase productivity, please contact me via-[email](mailto:grim@reaperworld.com) or by opening an issue and let me know!-----
-----
-Convey is built around a concept that I call a build container. A build-container is a container that has all of the dependencies to turn an input into-something else. This could be source code or even just data processing. For-example the `convey/go-build` image is a simple wrapper around the `golang`-image that just builds a project instead of installing it. You can find more-information on build containers-[here](http://blog.terranillius.com/post/docker_builder_pattern/).-Convey is built around this concept to allow you to build/process anything on-any platform while at the same time protecting the host from a malicious-config. This protection is provided by not exposing dangerous options like-volume mounts or port forwards while running containers. This is accomplished-by creating a volume a data volume at the start of the build plan and volume-mounting it into containers as they are run. This allows you to pass state-between modular tasks that can be reused between multiple plans.-Once built, convey can build itself entirely. This is done by using an import-task to copy the source code into the workspace. Once that stage is complete,-it runs another stage that builds for linux-x86_64, windows-x86_64, and-darwin-x86_64 in parallel. The final stage will take those compiled binaries-and export them back to the hosts file system.-Of course you don't have to export back to the host file system. Since these-are just containers, you could instead upload them to your staging environment,-packagecloud.io, bintray.com, whatever. Or you could export to the host and-create another plan that will import the artifacts and then publish them.-----
-There are a few ways you can install convey. The easiest is to grab it from-[Source Forge](https://sourceforge.net/projects/pidgin/files/convey/) section.-If you want to use the version currently in development and have a golang-environment setup, you can run `go install keep.imfreedom.org/grim/convey` and-it'll install into your `$GOPATH`.-----
- Usage: convey <command>- Convey is a container pipeline runner.- -h, --help Show context-sensitive help.- --color Enable colorized output.- -v, --verbose Be more verbose- version Show the version and exit- Run "convey <command> --help" for more information on a command.+This project has been used for awhile in production environment, but every +evironment is different. So, if you find issues, or are looking for ways to +help, please check out our +[issue tracker](https://issues.imfreedom.org/issues/CONVEY?u=1). - Usage: convey run [<plans> ...]- [<plans> ...] The names of the plans to run- -h, --help Show context-sensitive help.- --color Enable colorized output.- -v, --verbose Be more verbose- -f, --config-file=FILE The config file to load- -S, --force-sequential Force concurrent stages to be ran sequentially- --keep-workspace Keep the workspace directory after running- --timeout=DURATION The maximum amount of time a plan can run. 0 to disable. Units must be- -e, --env=ENV,... Set an environment variable- Show the version and exit- -h, --help Show context-sensitive help.- --color Enable colorized output.- -v, --verbose Be more verbose-Documentation for this format can be found in [REFERENCE.md](REFERENCE.md).--- a/REFERENCE.md Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,171 +0,0 @@
-Configuring convey is done via a file named `convey.yml`. This file defines-the tasks as well as the plans. This document explains how that file is-structured and what options are available.-There are a handful of examples in the [examples/](examples/) directory with a-README.md that describes which each is showing.-The complete reference for convey.yml can be found below.-The environment section defines a list of environment variables to set for the-It should be specified in a `NAME` or `NAME=VALUE` format. If no value is-provided, the value of the variable from the host will be provided if it is-Since there are multiple places where environment variables can be set, they-must all be merged together before being passed to a task.-Environment variables can be set at the `config-file`, `plan`, `stage`, `task`,-and command line levels. They are merged in that order, with the last one-taking precedence over the previous.-In the following example, when the `env1` task is run, the `FOO` environment-variable will be set to `baz`, but when the `env2` task is run, the `FOO`-environment variable will be set to bar- image: docker.io/alpine:edge- image: docker.io/alpine:Edge-In the next example, the stage is overriding the config-file value. So `env1`-still has a value of `baz` for the environment variable `FOO`, while `env2` has- image: docker.io/alpine:edge- image: docker.io/alpine:Edge-----
-The plans sections defines your execution plans which tie everything together-by organizing `tasks` into `stages` into the order that they will be executed.-Each plan is defined by a name in the plans section.-----
-Plans themselves are pretty straight forward. They group `stages` with an-| Name | Required | Description |-| ----------- | -------- | ----------- |-| environment | | A list of environment variables to set. They should be specified in a `NAME` or `NAME=VALUE` format. If no value is provided, the value of the variable from the host will be provided if it is available. These environment variables will be applied on top of any that were set at the config-file level or a meta-plan that contains this plan. |-| stages | Yes | A list of `stages` to be run as part of this `plan` in the order that they should be run in. |-----
-Stages group `tasks` together into a logical unit. They can be run-sequentially or concurrently.-| Name | Required | Default | Description |-| ----------- | -------- | ------- | ----------- |-| enabled | | true | Whether or not to run the stage at all. |-| concurrent | | false | Whether or not the tasks should be run at the same time. |-| environment | | | A list of environment variables to set. The should be specified in a `NAME` or `NAME=VALUE` format. If no value is provided, the value of the variable from the host will be provided if it is available. These environment variables will be applied on top of any that were set at the top-level and the plan level. |-| name | | the idex of the stage | A name to give the stage.-| run | No | on-success | When a stage should be run. Possible values are `on-success`, `on-failure`, or `always`. |-| tasks | Yes | | A list of task names to be run as part during this stage. If running sequentially they are run in the order that they are provided. If you are just specifying a single task, you can just pass use it's name not in a list. |-----
-Meta plans are used to group plans together and run them in serial. This is-also possible via the command line by specifying multiple plans to run.-Meta plans contain a single attribute which is the list of `plans` to run.-| Name | Required | Description |-| ----------- | -------- | ----------- |-| environment | | A list of environment variables to set. They should be specified in a `NAME` or `NAME=VALUE` format. If no value is provided, the value of the variable from the host will be provided if it is available. These environment variables will be applied on top of any that were set at the config-file level. |-| plans | Yes | A list of `plans` to run in the order they should be run in. |- - BUILD_TYPE=production-The documentation for the available task types can be found below:-* [Convey](tasks/README.md)-* [Docker](docker/README.md) (deprecated)-* [Podman](podman/README.md)-* [Script](script/README.md)--- a/docker/README.md Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,304 +0,0 @@
-Since version 0.15.0 convey no longer uses Docker and instead uses podman.-The Docker tasks are currently still available for backwards compatibility, but-will be removed in a future version. The do a best effort to apply their-original functionality to the podman tasks but not everything maps 100%. Please-see individual task documentation for additional information.-----
-> The docker/build task has been deprecated since version 0.15.0. Use the-> podman/build task instead.-This task will build a container image.-**NOTE:** arguments and files are not currently mapped into the podman/build-| Name | Required | Default | Description |-| ---------- | -------- | ------- | ----------- |-| arguments | | | A list of build arguments to pass to the build. |-| dockerfile | Yes | | The dockerfile to build. |-| files | | | A list of files that should be made available for the build. |-| labels | | | A list of labels to set on the container image being built. |-| tag | | | A tag to apply to the image. |-| tags | | | A list of tags to be applied to the image. |-| target | | | The name of the target to build in a multi stage dockerfile. |-----
-> The docker/build task has been deprecated and has no replacement.-The functionality of this task has been removed and the task now just fails.-If you have a use case for this task and would like to keep it, please file-and issue in our issue tracker.-----
-> The docker/export task has been deprecated since version 0.15.0. Use the-> convey/export task instead.-This task will export files from the workspace to the host filesystem relative-to the convey.yml used for the run.-| Name | Required | Default | Description |-| ------ | -------- | ------- | ----------- |-| files | Yes | | A single filename, source:destination, or a list of filenames and/or source:destinations. |- - binary:binary-linux-x86_64-----
-> The docker/import task has been deprecated since version 0.15.0. Use the-> convey/import task instead.-This task will import files from the host filesystem relative to the convey.yml-used for the run and put them into the workspace.-| Name | Required | Default | Description |-| ------ | -------- | ------- | ----------- |-| files | Yes | | A single filename, source:destination, or a list of filenames and/or source:destinations. |-----
-> The docker/login task has been deprecated since version 0.15.0. Use the-> podman/login task instead.-This task allows you to authorize to a container registry.-| Name | Required | Default | Description |-| --------- | -------- | --------- | ----------- |-| username | Yes | | The username to use. |-| password | Yes | | The password to use. |-| server | | docker.io | The registry to login to. |-----
-> The docker/logout task has been deprecated since version 0.15.0. Use the-> podman/logout task instead.-This task allows you to unauthenticate from a container registry.-| Name | Required | Default | Description |-| --------- | -------- | --------- | ----------- |-| server | | docker.io | The registry to logout of. |- server: regsitry.my.domain:5000-----
-> The docker/pull task has been deprecated since version 0.15.0. Use the-> podman/pull task instead.-This task allows you to pull down a container image. If the image is private,-be use to run a `docker/login` task first.-| Name | Required | Default | Description |-| ------ | -------- | ------- | ----------- |-| image | | | The name of the image include the tag. |-| images | | | A list of image names including the tags. |-At least one image must be supplied by either the `image` or `images`-attribute. If both are specified, `image` will be prepended to the list from- image: gliderlabs/alpine:edge-----
-> The docker/push task has been deprecated since version 0.15.0. Use the-> podman/push task instead.-This task allows you to push a local container image to a registry. If the-repository on the registry is private, be use to run a `docker/login` task-| Name | Required | Default | Description |-| ------ | -------- | ------- | ----------- |-| image | | | The name of the image include the tag. |-| images | | | A list of image names including the tags. |-At least one image must be supplied by either the `image` or `images`-attribute. If both are specified, `image` will be prepended to the list from- - registry.my.domain:5000/newimage:main-latest- - registry.my.domain:5000/newimage:main-deadbeef-----
-> The docker/remove task has been deprecated since version 0.15.0. Use the-> podman/remove task instead.-This task will remove an image from the local machine.-| Name | Required | Default | Description |-| ------ | -------- | ------- | ----------- |-| image | | | The name of the image include the tag. |-| images | | | A list of image names including the tags. |-| quiet | | false | True if a missing image should not count as a failure. |- - registry.my.domain:5000/newimage:main-latest- - registry.my.domain:5000/newimage:main-deadbeef-----
-> The docker/run task has been deprecated since version 0.15.0. Use the-> podman/run task instead.-This task will run a container with the workspace mounted.-**NOTE:** the detach and healthcheck attributes are not mapped to the-podman/run task and are not expected to be in the future. If you have a use-case for this, please open an issue on our issue tracker.-| Name | Required | Default | Description |-| ----------- | -------- | ------- | ----------- |-| command | | | The command to run in the container. This is only necessary if the image does not provide a command by default. |-| detach | | false | This is deprecated and no longer support. |-| entrypoint | | | The entrypoint to use for the container. This is only necessary if the image does not provide on by default or if you want to override the images default entrypoint. |-| environment | | | A list of environment variables to set. This should be specified in a `NAME` or `NAME=VALUE` format. |-| healthcheck | | | THis is deprecated and no longer support. |-| hostname | | | A custom hostname to set inside the container. |-| image | Yes | | The image include the registry and tag to run. |-| labels | | | A list of labels to set on the image being run. |-| script | | | A list of commands to run inside of the container. |-| shell | | | The shell to use with the script attribute above. |-| user | | | The user to run the container as. |-| workdir | | | The working directory inside the container. |-| workspace | | | The path to mount the convey workspace at inside of the container. |-A basic example where the image knows everything to do.-A basic example using a a standard image to do something else.- image: debian:jessie-slim- - wget https://somedomain.tld/file1- - wget https://somedomain.tld/file1.sha256sum- - sha256sum -c file1.sha256sum-----
-> The docker/tag task has been deprecated since version 0.15.0. Use the-> podman/tag task instead.-This task will tag existing images on the host.-| Name | Required | Default | Description |-| ----------- | -------- | ------- | ----------- |-| source | Yes | | The full source image including the registry and tag to tag. |-| destination | Yes | | The destination tag include the registry and tag to create. |- source: registry.my.domain:5000/newimage:latest- destination: registry.my.domain:5000/newimage:dev--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/about.md Sat Mar 26 06:27:05 2022 -0500
@@ -0,0 +1,19 @@
+[  ](https://issues.imfreedom.org/issues/CONVEY?u=1) +[  ](https://keep.imfreedom.org/grim/convey) +Convey is a pipeline for running containers and protecting the host as much as +possible. It accomplishes this goal by creating a volume and making it +available to each item in the pipeline. +This project has been used for awhile in production environment, but every +evironment is different. So, if you find issues, or are looking for ways to +help, please check out our +[issue tracker](https://issues.imfreedom.org/issues/CONVEY?u=1). --- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/concepts.md Sat Mar 26 06:27:05 2022 -0500
@@ -0,0 +1,28 @@
+Convey is built around a concept that we call a build container. A build +container is a container that has all of the dependencies to turn an input into +something else. This could be source code or even just data processing. You can +find more information on build containers +[here](http://blog.terranillius.com/post/docker_builder_pattern/). +Convey is built around this concept to allow you to build/process anything on +any platform while at the same time protecting the host from a malicious +config. This protection is provided by not exposing dangerous options like +volume mounts or port forwards while running containers. This is accomplished +by using a shared volume and mounting it into containers as they are run. This +allows you to pass state between modular tasks that can be reused between +Once built, convey can build itself entirely. This is done by using an import +task to copy the source code into the workspace. Once that stage is complete, +it runs another stage that builds for linux-x86_64, windows-x86_64, +darwin-x86_64, and freebsd-x86_64 in parallel. The final stage will take those +compiled binaries and export them back to the hosts file system. You can +see this plan in its entirty +[here](https://keep.imfreedom.org/grim/convey/file/default/convey.yml). +Of course you don't have to export back to the host file system. Since these +are just containers, you could instead upload them to your staging environment, +packagecloud.io, bintray.com, whatever. Or you could export to the host and +create another plan that will import the artifacts and then publish them. --- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/configuration.md Sat Mar 26 06:27:05 2022 -0500
@@ -0,0 +1,172 @@
+Configuring convey is done via a file named `convey.yml`. This file defines +the tasks as well as the plans. This document explains how that file is +structured and what options are available. +The environment section defines a list of environment variables to set for the +It should be specified in a `NAME` or `NAME=VALUE` format. If no value is +provided, the value of the variable from the host will be provided if it is +Since there are multiple places where environment variables can be set, they +must all be merged together before being passed to a task. +Environment variables can be set at the `config-file`, `plan`, `stage`, `task`, +and command line levels. They are merged in that order, with the last one +taking precedence over the previous. +In the following example, when the `env1` task is run, the `FOO` environment +variable will be set to `baz`, but when the `env2` task is run, the `FOO` +environment variable will be set to bar + image: docker.io/alpine:edge + image: docker.io/alpine:Edge +In the next example, the stage is overriding the config-file value. So `env1` +still has a value of `baz` for the environment variable `FOO`, while `env2` has + image: docker.io/alpine:edge + image: docker.io/alpine:Edge +The plans sections defines your execution plans which tie everything together +by organizing `tasks` into `stages` into the order that they will be executed. +Each plan is defined by a name in the plans section. +Plans themselves are pretty straight forward. They group `stages` with an +| Name | Required | Description | +| ----------- | -------- | ----------- | +| environment | | A list of environment variables to set. They should be specified in a `NAME` or `NAME=VALUE` format. If no value is provided, the value of the variable from the host will be provided if it is available. These environment variables will be applied on top of any that were set at the config-file level or a meta-plan that contains this plan. | +| stages | Yes | A list of `stages` to be run as part of this `plan` in the order that they should be run in. | +Stages group `tasks` together into a logical unit. They can be run +sequentially or concurrently. +| Name | Required | Default | Description | +| ----------- | -------- | ------- | ----------- | +| enabled | | true | Whether or not to run the stage at all. | +| concurrent | | false | Whether or not the tasks should be run at the same time. | +| environment | | | A list of environment variables to set. The should be specified in a `NAME` or `NAME=VALUE` format. If no value is provided, the value of the variable from the host will be provided if it is available. These environment variables will be applied on top of any that were set at the top-level and the plan level. | +| name | | the idex of the stage | A name to give the stage. +| run | No | on-success | When a stage should be run. Possible values are `on-success`, `on-failure`, or `always`. | +| tasks | Yes | | A list of task names to be run as part during this stage. If running sequentially they are run in the order that they are provided. If you are just specifying a single task, you can just pass use it's name not in a list. | +Meta plans are used to group plans together and run them in serial. This is +also possible via the command line by specifying multiple plans to run. +Meta plans contain a single attribute which is the list of `plans` to run. +| Name | Required | Description | +| ----------- | -------- | ----------- | +| environment | | A list of environment variables to set. They should be specified in a `NAME` or `NAME=VALUE` format. If no value is provided, the value of the variable from the host will be provided if it is available. These environment variables will be applied on top of any that were set at the config-file level. | +| plans | Yes | A list of `plans` to run in the order they should be run in. | + - BUILD_TYPE=production +The documentation for the available task types can be found below: +* [Docker](docker.md) (deprecated) --- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/convey.md Sat Mar 26 06:27:05 2022 -0500
@@ -0,0 +1,103 @@
+The convey tasks provides some intrinsic tasks that convey provides. +A clean task will remove files from the host relative and limited to the +directory containing the `convey.yml` for the run. +| Name | Required | Default | Description | +| --------- | -------- | ------- | ----------- | +| files | Yes | | A list of filenames relative to the convey.yml file to remove. | +An export task will move files from the workspace to the host underneath the +directory containing the `convey.yml` file was found. +| Name | Required | Default | Description | +| --------- | -------- | ------- | ----------- | +| files | Yes | | A single filename or a list of files to copy from the workspace to the host. Files can be specified in one of two forms which can be mixed. The first is `source:destination` and the other is `filename` where filename will be used for both the host and the volume. | + - binary:binary-linux-x86_64 +An import task copies files from the host to the workspace. It has one required +attribute named files. This is a list of files relative to the directory +containing the convey.yml file that will be copied into the workspace. +| Name | Required | Default | Description | +| ----- | -------- | ------- | ----------- | +| files | Yes | | A single filename or a list of files to copy from the host to the workspace. Files can be specified in one of two forms which can be mixed. The first is `source:destination` and the other is `filename` where filename will be used for both the host and the volume. | +A noop task does nothing. It is a "NO OPeration" task. It's used primarily in +testing, but could be useful for stubbing stuff out or debugging. --- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/docker.md Sat Mar 26 06:27:05 2022 -0500
@@ -0,0 +1,327 @@
+> ***NOTE:*** Since version 0.15.0 convey no longer uses Docker and instead +uses podman. The Docker tasks are currently still available for backwards +compatibility, but will be removed in a future version. They do a best effort +to apply their original functionality to the podman tasks but not everything +maps 100%. Please see individual task documentation for additional information. +> ***DEPRECATED:*** The docker/build task has been deprecated since version +0.15.0. Use the podman/build task instead. +This task will build a container image. +**NOTE:** arguments and files are not currently mapped into the podman/build +| Name | Required | Default | Description | +| ---------- | -------- | ------- | ----------- | +| arguments | | | A list of build arguments to pass to the build. | +| dockerfile | Yes | | The dockerfile to build. | +| files | | | A list of files that should be made available for the build. | +| labels | | | A list of labels to set on the container image being built. | +| tag | | | A tag to apply to the image. | +| tags | | | A list of tags to be applied to the image. | +| target | | | The name of the target to build in a multi stage dockerfile. | +> ***DEPRECATED:*** The docker/environment task has been deprecated since +version 0.15.0 and has no replacement. +The functionality of this task has been removed and the task now just fails. +If you have a use case for this task and would like to keep it, please file +and issue in our issue tracker. +> ***DEPRECATED:*** The docker/export task has been deprecated since version +0.15.0. Use the convey/export task instead. +This task will export files from the workspace to the host filesystem relative +to the `convey.yml` used for the run. +| Name | Required | Default | Description | +| ------ | -------- | ------- | ----------- | +| files | Yes | | A single filename, source:destination, or a list of filenames and/or source:destinations. | + - binary:binary-linux-x86_64 +> ***DEPRECATED:*** The docker/import task has been deprecated since version +0.15.0. Use the convey/import task instead. +This task will import files from the host filesystem relative to the +`convey.yml` used for the run and put them into the workspace. +| Name | Required | Default | Description | +| ------ | -------- | ------- | ----------- | +| files | Yes | | A single filename, source:destination, or a list of filenames and/or source:destinations. | +> ***DEPRECATED:*** The docker/login task has been deprecated since version +0.15.0. Use the podman/login task instead. +This task allows you to authorize to a container registry. +| Name | Required | Default | Description | +| --------- | -------- | --------- | ----------- | +| username | Yes | | The username to use. | +| password | Yes | | The password to use. | +| server | | docker.io | The registry to login to. | +> ***DEPRECATED:*** The docker/logout task has been deprecated since version +0.15.0. Use the podman/logout task instead. +This task allows you to unauthenticate from a container registry. +| Name | Required | Default | Description | +| --------- | -------- | --------- | ----------- | +| server | | docker.io | The registry to logout of. | + server: regsitry.my.domain:5000 +> ***DEPRECATED:*** The docker/pull task has been deprecated since version +0.15.0. Use the podman/pull task instead. +This task allows you to pull down a container image. If the image is private, +be use to run a `docker/login` task first. +| Name | Required | Default | Description | +| ------ | -------- | ------- | ----------- | +| image | | | The name of the image include the tag. | +| images | | | A list of image names including the tags. | +At least one image must be supplied by either the `image` or `images` +attribute. If both are specified, `image` will be prepended to the list from + image: gliderlabs/alpine:edge +> ***DEPRECATED:*** The docker/push task has been deprecated since version +0.15.0. Use the podman/push task instead. +This task allows you to push a local container image to a registry. If the +repository on the registry is private, be use to run a `docker/login` task +| Name | Required | Default | Description | +| ------ | -------- | ------- | ----------- | +| image | | | The name of the image include the tag. | +| images | | | A list of image names including the tags. | +At least one image must be supplied by either the `image` or `images` +attribute. If both are specified, `image` will be prepended to the list from + - registry.my.domain:5000/newimage:main-latest + - registry.my.domain:5000/newimage:main-deadbeef +> ***DEPRECATED:*** The docker/remove task has been deprecated since version +0.15.0. Use the podman/remove task instead. +This task will remove an image from the local machine. +| Name | Required | Default | Description | +| ------ | -------- | ------- | ----------- | +| image | | | The name of the image include the tag. | +| images | | | A list of image names including the tags. | +| quiet | | false | True if a missing image should not count as a failure. | + - registry.my.domain:5000/newimage:main-latest + - registry.my.domain:5000/newimage:main-deadbeef +> ***DEPRECATED:*** The docker/run task has been deprecated since version +0.15.0. Use the podman/run task instead. +This task will run a container with the workspace mounted. +> ***NOTE:*** the detach and healthcheck attributes are not mapped to the +podman/run task and are not expected to be in the future. If you have a use +case for this, please open an issue on our issue tracker. +| Name | Required | Default | Description | +| ----------- | -------- | ------- | ----------- | +| command | | | The command to run in the container. This is only necessary if the image does not provide a command by default. | +| detach | | false | This is deprecated and no longer support. | +| entrypoint | | | The entrypoint to use for the container. This is only necessary if the image does not provide on by default or if you want to override the image's default entrypoint. | +| environment | | | A list of environment variables to set. This should be specified in a `NAME` or `NAME=VALUE` format. | +| healthcheck | | | THis is deprecated and no longer support. | +| hostname | | | A custom hostname to set inside the container. | +| image | Yes | | The image include the registry and tag to run. | +| labels | | | A list of labels to set on the image being run. | +| script | | | A list of commands to run inside of the container. | +| shell | | | The shell to use with the script attribute above. | +| user | | | The user to run the container as. | +| workdir | | | The working directory inside the container. | +| workspace | | | The path to mount the convey workspace at inside of the container. | +A basic example where the image knows everything to do. +A basic example using a a standard image to do something else. + image: debian:jessie-slim + - wget https://somedomain.tld/file1 + - wget https://somedomain.tld/file1.sha256sum + - sha256sum -c file1.sha256sum +> ***DEPRECATED:*** The docker/tag task has been deprecated since version +0.15.0. Use the podman/tag task instead. +This task will tag existing images on the host. +| Name | Required | Default | Description | +| ----------- | -------- | ------- | ----------- | +| source | Yes | | The full source image including the registry and tag to tag. | +| destination | Yes | | The destination tag include the registry and tag to create. | + source: registry.my.domain:5000/newimage:latest + destination: registry.my.domain:5000/newimage:dev --- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/examples.md Sat Mar 26 06:27:05 2022 -0500
@@ -0,0 +1,120 @@
+This section contains a number of examples. +This example shows your traditional clone, test, build, deploy, and report for + image: docker.io/rwgrim/docker-noop + image: docker.io/rwgrim/docker-noop + image: docker.io/rwgrim/docker-noop + image: docker.io/rwgrim/docker-noop + image: docker.io/rwgrim/docker-noop + image: docker.io/rwgrim/docker-noop + image: docker.io/rwgrim/docker-noop +You can use metaplans to group disperate plans into a single plan. +default-plan: everything + image: docker.io/alpine:edge + image: docker.io/alpine:edge +This example logs into the the registry at the start of the plan and regardless +of the result of the plan will always logout before exiting. It also will look +for the `REGISTRY_USERNAME` and `REGISTRY_PASSWORD` on the host to keep them + - REGISTRY_HOSTNAME=registry.example.com + server: ${REGISTRY_HOSTNAME} + username: ${REGISTRY_USERNAME} + password: ${REGISTRY_PASSWORD} + server: ${REGISTRY_HOSTNAME} --- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/history.md Sat Mar 26 06:27:05 2022 -0500
@@ -0,0 +1,19 @@
+Convey was created out of the need to build [Pidgin](https://pidgin.im) and its +supporting libraries on multiple Linux distributions, Windows and MacOS. While +there are many continuous integration tools out there, all of them still +require maintenance and can only be used by the project itself. +This becomes a problem when you have a community of plugin developers who would +also like to build against all of its supported operating systems but can't and +shouldn't need to put forth the effort and maintenance involved with using +This is where Convey's concept of [build containers](concepts.md) +comes into use. Once you have all the dependencies required to build something, +like a Pidgin plugin, you are then able to share that container image with +everyone using this system and they are then able to use that image to build +against. So a project like Pidgin can supply build images containing the most +recent releases with all of the build dependencies for multiple platforms and +then plugin developers can use that image to test their plugins against. --- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/installation.md Sat Mar 26 06:27:05 2022 -0500
@@ -0,0 +1,8 @@
+There are a few ways you can install convey. The easiest is to grab it from +[Source Forge](https://sourceforge.net/projects/pidgin/files/convey/) section. +If you want to use the version currently in development and have a golang +environment setup, you can run `go install keep.imfreedom.org/grim/convey` and +it'll install into your `$PATH`. --- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/podman.md Sat Mar 26 06:27:05 2022 -0500
@@ -0,0 +1,207 @@
+Podman is a container runtime that runs daemonless as a normal user. It has +been adopted as the only container run time since convey 0.15.0. +This task will build a container image. +| Name | Required | Default | Description | +| ------------- | -------- | ------------------- | ----------- | +| annotations | | | A list of annotations for the container image. | +| containerfile | Yes | | The containerfile to build. | +| context | | ${CONVEY_WORKSPACE} | The context to pass to podman build. This path needs to build under the convey workspace which means all files for the build must first be imported into the workspace. | +| tags | | | A list of tags or a single tag to be applied to the image. | +| target | | | The name of the target to build in a multi stage containerfile. | + containerfile: Dockerfile +This task allows you to authorize to a container registry. +| Name | Required | Default | Description | +| --------- | -------- | --------- | ----------- | +| password | Yes | | The password to use. | +| registry | | docker.io | The registry to login to. | +| username | Yes | | The username to use. | +This task allows you to unauthenticate from a container registry. +| Name | Required | Default | Description | +| -------- | -------- | --------- | ----------- | +| registry | | docker.io | The registry to logout of. | + registry: regsitry.my.domain:5000 +This task allows you to pull down a container image. If the image is private, +be use to run a `podman/login` task first. +| Name | Required | Default | Description | +| ---- | -------- | ------- | ----------- | +| tags | Yes | | A list of image names or a single image name including the tags. | + tags: gliderlabs/alpine:edge +This task allows you to push a local container image to a registry. If the +repository on the registry is private, be use to run a `podman/login` task +| Name | Required | Default | Description | +| ---- | -------- | ------- | ----------- | +| tags | Yes | | A list of image names or a single image name including the tags. | + - registry.my.domain:5000/newimage:main-latest + - registry.my.domain:5000/newimage:main-deadbeef +This task will remove an image from the local machine. +| Name | Required | Default | Description | +| ----- | -------- | ------- | ----------- | +| tags | | | A list of image names including the tags. | +| quiet | | false | True if a missing image should not count as a failure. | + - registry.my.domain:5000/newimage:main-latest + - registry.my.domain:5000/newimage:main-deadbeef +This task will run a container with the workspace mounted. +| Name | Required | Default | Description | +| ----------- | -------- | ------- | ----------- | +| annotations | | | A list of annotations to set on the container being run. | +| command | | | The command to run in the container. This is only necessary if the image does not provide a command by default. | +| entrypoint | | | The entrypoint to use for the container. This is only necessary if the image does not provide on by default or if you want to override the image's default entrypoint. | +| environment | | | A list of environment variables to set. This should be specified in a `NAME` or `NAME=VALUE` format. | +| hostname | | | A custom hostname to set inside the container. | +| image | Yes | | The image include the registry and tag to run. | +| script | | | A list of commands to run inside of the container. | +| shell | | | The shell to use with the script attribute above. | +| user | | | The user to run the container as. | +| workdir | | | The working directory inside the container. | +| workspace | | | The path to mount the convey workspace at inside of the container. | +A basic example where the image knows everything to do. +A basic example using a a standard image to do something else. + - wget https://somedomain.tld/file1 + - wget https://somedomain.tld/file1.sha256sum + - sha256sum -c file1.sha256sum +This task will tag existing images on the host. +| Name | Required | Default | Description | +| ------- | -------- | ------- | ----------- | +| image | Yes | | The full source image including the registry and tag to tag. | +| targets | Yes | | The destination tag include the registry and tag to create. | + image: registry.my.domain:5000/newimage:latest + targets: registry.my.domain:5000/newimage:dev --- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/script.md Sat Mar 26 06:27:05 2022 -0500
@@ -0,0 +1,59 @@
+Script is a set of tasks for running scripts on the host. These can be +dangerous and should be used sparingly. +Available on UNIX like platforms including BSD, macOS, and Linux, but will +raise an error if attempted to be used on Windows. +Either a filename or commands must be specified, but specifying both is an +error as Convey will not know which one you want to prioritize. When commands +are specified, a temporary file will be created containing the given commands. +| Name | Required | Default | Description | +| ----------- | -------- | ------- | ----------- | +| commands | | | A list of commands to run as the script. | +| environment | | | A list of environment variables to set. This should be specified in a `NAME` or `NAME=VALUE` format. | +| filename | | | The name of a script file to run. The file must exist in the directory containing the current convey configuration file or a subdirectory. | +| shell | | | The shell to use. If not specified the users default shell will be used. | +Run an ahhoc script with a single command. The commands parameter will work +with a single string or a list of strings +Run an adhoc script in Z Shell --- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/usage.md Sat Mar 26 06:27:05 2022 -0500
@@ -0,0 +1,59 @@
+Convey is a terminal based application. It has a few subcommands, but it will +primarily because called with the [run](#run) subcommand. +Convey is a container pipeline runner. + -h, --help Show context-sensitive help. + --color Enable colorized output. + -v, --verbose Be more verbose + version Show the version and exit +Run "convey <command> --help" for more information on a command. +Usage: convey run [<plans> ...] + [<plans> ...] The names of the plans to run + -h, --help Show context-sensitive help. + --color Enable colorized output. + -v, --verbose Be more verbose + -f, --config-file=FILE The config file to load + -S, --force-sequential Force concurrent stages to be ran sequentially + --keep-workspace Keep the workspace directory after running + --timeout=DURATION The maximum amount of time a plan can run. 0 to disable. Units must be + -e, --env=ENV,... Set an environment variable +Show the version and exit + -h, --help Show context-sensitive help. + --color Enable colorized output. + -v, --verbose Be more verbose --- a/examples/README.md Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,73 +0,0 @@
-This directory contains quite a few examples of how to use convey.-## default-plan-alias.yml-A simple plan that aliases the default plan.-A simple plan to show how you can detach a container.-A simple plan to show how you can specify health commands for a detached-This example shows how environment substitution works in your config file.-This example shows how you can use meta-plans to group multiple plans together.-This example shows how environment substitution overriding works and uses a-`-override.yml` file as well.-This example shows how to have one file extend another, inheriting all of the-plans and tasks that are not otherwise overwritten by the configuration file.-This example shows how to have one file extend another and specific stages of a-plan can be replaced in the extending file.-This example shows how to expand an environment variable into a list in the-context of a extended task.-## environment-from-file.yml-This example shows how to inject variables into the environment from a file in-This example shows how you can login and logout of a Docker registry by using-This example shows how to use the script attribute of a run task.-This example shows how you can specify an ssh identity to automatically turn on-A simple example showing how to use the run attribute of a stage.-This example shows your traditional clone, test, build, deploy, and report for--- a/examples/base.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,34 +0,0 @@
-# This is the base file to extends.yml. It is a valid convey.yml file in its-# own right and can be executed as such. However, the main use case for this-# feature is to make "abstract" plans which may contain a useful toolset of-# tasks across projects and environments.- command: echo "$PREFIX one"- command: echo "$PREFIX two"--- a/examples/default-plan-alias.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,12 +0,0 @@
- default-plan: not-the-default--- a/examples/detach-health.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,20 +0,0 @@
- command: wget -O - http://localhost--- a/examples/detach.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,11 +0,0 @@
--- a/examples/disabled-stage.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,16 +0,0 @@
--- a/examples/environment-from-file.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,58 +0,0 @@
-# This plan shows how the inject plan can add additional-# environment variables accessible to your tasks during-# runtime. Running this with `-e X_FOO=4`, the output-# will be (in two parts):-# Notice that before the inject task, only X_FOO and X_BAR-# were set by the command line argument and the global env-# block, respectively. Afterwards, X_FOO's value did not-# change (as command line parameters take have precedence),-# X_BAR is overwritten, and X_BAZ is newly added.- type: docker/environment- - echo "X_FOO=${X_FOO}"- - echo "X_BAR=${X_BAR}"- - echo "X_BAZ=${X_BAZ}"--- a/examples/environment.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,19 +0,0 @@
- - 'echo version: ${VERSION}'- - 'echo special: ${SPECIAL}'- - 'echo git commit: ${GIT_COMMIT}'- - 'echo hg commit: ${HG_COMMIT}'--- a/examples/extends-merge.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,37 +0,0 @@
-# This plan extends another plan by overwriting the pre and post-# stages of a plan defined in the parent config. This shows how-# to build "abstract" plans which can be extended in ways that-# allow blocks of plans to be replaced.- command: echo "<= before"- command: echo "=> after"--- a/examples/extends.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,33 +0,0 @@
-# This plan extends another plan by overwriting one of the tasks-# and defining its own, then defining its own plan. The two are-# merged where anything in the extending file overwrites the base.- command: echo "${PREFIX} TWO"- command: echo "${PREFIX} three"- # one is inherited from base.yml- # two is overridden from base.yml- # three is newly defined--- a/examples/login-logout.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,22 +0,0 @@
- - DOCKER_REGISTRY=registry- - DOCKER_USERNAME=username- - DOCKER_PASSWORD=password- server: ${DOCKER_REGISTRY}- username: ${DOCKER_USERNAME}- password: ${DOCKER_PASSWORD}- server: ${DOCKER_REGISTRY}--- a/examples/metaplans.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,27 +0,0 @@
-default-plan: everything--- a/examples/multi-stage/Dockerfile Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,13 +0,0 @@
-FROM alpine:edge as multi-stage-base-# create our first child-FROM multi-stage-base as multi-stage-left-# create our second child-FROM multi-stage-base as multi-stage-right--- a/examples/multi-stage/README.md Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,12 +0,0 @@
-In this example, the `Dockerfile` defines three images. A base with two-`docker build` has a `--target` option that will allow you to select which-image to build in a `Dockerfile` like this. The value for `--target` is the-name given to the image which is the part after the `as`. In convey you can-set the `target` attribute to set this value.-The `convey.yml` will then build both child images and then run and remove--- a/examples/multi-stage/convey.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,43 +0,0 @@
- target: multi-stage-left- target: multi-stage-right- tags: multi-stage-right- image: multi-stage-left- image: multi-stage-right--- a/examples/override-override.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,2 +0,0 @@
- - source=global-override--- a/examples/override.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,23 +0,0 @@
-# this config shows how the environment override works including with an-# override file and via the command line.-# Try commenting out the source environment variable in one of the sections,-# as well as specifying it on the command line to get a feel for it. Don't-# forget the -override file (override-override.yml)--- a/examples/script.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,13 +0,0 @@
- - echo "hello from alpine"--- a/examples/ssh-identities.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,13 +0,0 @@
--- a/examples/traditional.yml Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,45 +0,0 @@
- image: rwgrim/docker-noop- image: rwgrim/docker-noop- image: rwgrim/docker-noop- image: rwgrim/docker-noop- image: rwgrim/docker-noop- image: rwgrim/docker-noop- image: rwgrim/docker-noop--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mkdocs.yml Sat Mar 26 06:27:05 2022 -0500
@@ -0,0 +1,22 @@
+site_url: https://docs.imfreedom.org/convey/ +copyright: Copyright © 2016-2022 <a href="https://reaperworld.com">Gary Kramlich</a> +repo_url: https://keep.imfreedom.org/grim/convey/ + - Concepts: concepts.md + - Installation: installation.md + - Configuration: configuration.md + - Examples: examples.md --- a/podman/README.md Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,193 +0,0 @@
-Podman is a container runtime that runs daemonless as a normal user. It has-been adopted as the only container run time since convey 0.15.0.-----
-This task will build a container image.-| Name | Required | Default | Description |-| ------------- | -------- | ------------------- | ----------- |-| annotations | | | A list of annotations for the container image. |-| containerfile | Yes | | The containerfile to build. |-| context | | ${CONVEY_WORKSPACE} | The context to pass to podman build. This path needs to build under the convey workspace which means all files for the build must first be imported into the workspace. |-| tags | | | A list of tags or a single tag to be applied to the image. |-| target | | | The name of the target to build in a multi stage containerfile. |- containerfile: Dockerfile-----
-This task allows you to authorize to a container registry.-| Name | Required | Default | Description |-| --------- | -------- | --------- | ----------- |-| password | Yes | | The password to use. |-| registry | | docker.io | The registry to login to. |-| username | Yes | | The username to use. |-----
-This task allows you to unauthenticate from a container registry.-| Name | Required | Default | Description |-| -------- | -------- | --------- | ----------- |-| registry | | docker.io | The registry to logout of. |- registry: regsitry.my.domain:5000-----
-This task allows you to pull down a container image. If the image is private,-be use to run a `podman/login` task first.-| Name | Required | Default | Description |-| ---- | -------- | ------- | ----------- |-| tags | Yes | | A list of image names or a single image name including the tags. |- tags: gliderlabs/alpine:edge-----
-This task allows you to push a local container image to a registry. If the-repository on the registry is private, be use to run a `podman/login` task-| Name | Required | Default | Description |-| ---- | -------- | ------- | ----------- |-| tags | Yes | | A list of image names or a single image name including the tags. |-At least one image must be supplied by either the `image` or `images`-attribute. If both are specified, `image` will be prepended to the list from- - registry.my.domain:5000/newimage:main-latest- - registry.my.domain:5000/newimage:main-deadbeef-----
-This task will remove an image from the local machine.-| Name | Required | Default | Description |-| ----- | -------- | ------- | ----------- |-| tags | | | A list of image names including the tags. |-| quiet | | false | True if a missing image should not count as a failure. |- - registry.my.domain:5000/newimage:main-latest- - registry.my.domain:5000/newimage:main-deadbeef-----
-This task will run a container with the workspace mounted.-| Name | Required | Default | Description |-| ----------- | -------- | ------- | ----------- |-| annotations | | | A list of annotations to set on the container being run. |-| command | | | The command to run in the container. This is only necessary if the image does not provide a command by default. |-| entrypoint | | | The entrypoint to use for the container. This is only necessary if the image does not provide on by default or if you want to override the images default entrypoint. |-| environment | | | A list of environment variables to set. This should be specified in a `NAME` or `NAME=VALUE` format. |-| hostname | | | A custom hostname to set inside the container. |-| image | Yes | | The image include the registry and tag to run. |-| script | | | A list of commands to run inside of the container. |-| shell | | | The shell to use with the script attribute above. |-| user | | | The user to run the container as. |-| workdir | | | The working directory inside the container. |-| workspace | | | The path to mount the convey workspace at inside of the container. |-A basic example where the image knows everything to do.-A basic example using a a standard image to do something else.- - wget https://somedomain.tld/file1- - wget https://somedomain.tld/file1.sha256sum- - sha256sum -c file1.sha256sum-----
-This task will tag existing images on the host.-| Name | Required | Default | Description |-| ------- | -------- | ------- | ----------- |-| image | Yes | | The full source image including the registry and tag to tag. |-| targets | Yes | | The destination tag include the registry and tag to create. |- image: registry.my.domain:5000/newimage:latest- targets: registry.my.domain:5000/newimage:dev--- a/script/README.md Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,53 +0,0 @@
-Script is a set of tasks for running scripts on the host. These can be-dangerous and should be used sparingly.-----
-Available on UNIX like platforms including BSD, macOS, and Linux, but will-raise an error if attempted to be used on Windows.-Either a filename or commands must be specified, but specifying both is an-error as Convey will not know which one you want to prioritize. When commands-are specified, a temporary file will be created containing the given commands.-| Name | Required | Default | Description |-| ----------- | -------- | ------- | ----------- |-| commands | | | A list of commands to run as the script. |-| environment | | | A list of environment variables to set. This should be specified in a `NAME` or `NAME=VALUE` format. |-| filename | | | The name of a script file to run. The file must exist in the directory containing the current convey configuration file or a subdirectory. |-| shell | | | The shell to use. If not specified the users default shell will be used. |-Run an ahhoc script with a single command. The commands parameter will work-with a single string or a list of strings-Run an adhoc script in Z Shell--- a/tasks/README.md Thu Dec 23 17:12:45 2021 -0600
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,92 +0,0 @@
-The intrinsic package provides some intrinsic tasks that convey provides.-----
-A clean task will remove files from the host relative and limited to the-directory containing the convey.yml for the run.-| Name | Required | Default | Description |-| --------- | -------- | ------- | ----------- |-| files | Yes | | A list of filenames relative to the convey.yml file to remove. |-----
-An export task will move files from the workspace to the host underneath the-directory containing the convey.yml file was found.-| Name | Required | Default | Description |-| --------- | -------- | ------- | ----------- |-| files | Yes | | A single filename or a list of files to copy from the workspace to the host. Files can be specified in one of two forms which can be mixed. The first is `source:destination` and the other is `filename` where filename will be used for both the host and the volume. |- - binary:binary-linux-x86_64-----
-An import task copies files from the host to the workspace. It has one required-attribute named files. This is a list of files relative to the directory-containing the convey.yml file that will be copied into the workspace.-| Name | Required | Default | Description |-| ----- | -------- | ------- | ----------- |-| files | Yes | | A single filename or a list of files to copy from the host to the workspace. Files can be specified in one of two forms which can be mixed. The first is `source:destination` and the other is `filename` where filename will be used for both the host and the volume. |-----
-A noop task does nothing. It is a "No Operation" task. It's used primarily in-testing, but could be used for stubbing stuff out or debugging.
