+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 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.
+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 other available tools.
-
-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 Docker 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.
+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
+other available tools.
-This also works when it comes to deployments. You can create an image to deploy to [bintray](https://bintray.com/) so that users are able to specify options in their convey.yml and not have to worry about the specifics of how it's uploaded.
+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.
-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!
-
+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!
----
@@ -26,98 +36,97 @@
# Concepts
-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.
+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
-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.
+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.
-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.
+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.
----
# Installation
-There are a few ways you can install convey. The easiest is to grab it from the [downloads](https://bitbucket.org/rw_grim/convey/downloads/) section.
+There are a few ways you can install convey. The easiest is to grab it from
-If you want to use the version currently in development and have a golang environment setup, you can run `go install bitbucket.org/rw_grim/convey` and it'll install into your `$GOPATH`.
+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
- usage: convey [<flags>] <command> [<args> ...]
+## Basic
+
+ Usage: convey <command>
Convey is a container pipeline runner.
Flags:
- --help Show context-sensitive help (also try --help-long and --help-man).
- --version Show application version.
- --color Enable colorized output
- -l, --config-loader=convey Select the configuration loader
- -f, --config=CONFIG The config file name to use
- -c, --cpu-shares=CPU-SHARES The amount of cpu shares to give to a run task
- --docker-config=DOCKER-CONFIG
- Location of docker client config files
- -e, --env=ENV ... Set environment variables
- -S, --force-sequential Don't run anything concurrently
- -m, --memory=MEMORY The amount of memory to give the run task
- --ssh-agent A shortcut for --ssh-identity=*
- --ssh-identity=SSH-IDENTITY ...
- Enable ssh-agent for the given identities
- --timeout=15m The maximum amount of time a plan can run. 0 to disable. Units must be
- specified.
- -v, --verbose Be more verbose
- --disable-deprecated Allow the user of deprecated features
+ -h, --help Show context-sensitive help.
+ --color Enable colorized output.
+ -v, --verbose Be more verbose
Commands:
- help [<command>...]
- Show help.
-
- config
- Show a dump of the config file
+ run Run plans
+ version Show the version and exit
- environment
- List the environment variables that are available
+ Run "convey <command> --help" for more information on a command.
+
+## Run Command
+
+ Usage: convey run [<plans> ...]
- graphviz
- Output a graphviz diagram of the config file
+ Run plans
+
+ Arguments:
+ [<plans> ...] The names of the plans to run
- run* [<plan>...]
- Run a plan or metaplan
-
- list environment
- List the environment variables that are available.
+ Flags:
+ -h, --help Show context-sensitive help.
+ --color Enable colorized output.
+ -v, --verbose Be more verbose
- list metaplans
- List the metaplans defined in the configuration file.
+ -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
+ specified.
+ -e, --env=ENV,... Set an environment variable
+
+## Version Command
+
+ Usage: convey version
- list plans
- List the plans defined in the configuration file.
+ Show the version and exit
- list tasks
- List the tasks defined in the configuration file.
+ Flags:
+ -h, --help Show context-sensitive help.
+ --color Enable colorized output.
+ -v, --verbose Be more verbose
# Configuration
-Convey supports multiple configuration loader which can be specified by the `-l` command line argument.
-
-# Config Loaders
-
-Convey supports multiple different types of configs that it can load. Currently supported loaders are convey and bitbucket.
-
-## Convey
-
-Documentation for the built in format can be found in [REFERENCE.md](REFERENCE.md).
-The `convey` config is the one described above and is the default.
-
-# Bitbucket
-
-The `bitbucket` config is for [bitbucket-pipelines](https://bitbucket.org/product/features/pipelines) which will allow you to run your pipeline locally. Convey does a best attempt at emulating the pipelines environment, but your mileage may vary. If you're having problems, please open an issue.
-
-To use the bitbucket config loader, just run `convey -l bitbucket`. If there is a `bitbucket-pipelines.yml` file in the working directory, convey will happily run it.
-
-bitbucket pipelines does not have plans in the same sense that convey does, so if you do not specify one, convey will use the same heuristics that bitbucket-pipelines does to run the correct pipeline from the config.
-
-Also, since the `bitbucket-pipelines.yml` file is converted into the convey config format, `--graphviz`, `--list-plans`, and `--list-tasks` all work like normal as well.
-
+Documentation for this format can be found in [REFERENCE.md](REFERENCE.md).
