{"id":13850331,"url":"https://github.com/skx/deployr","last_synced_at":"2025-04-08T16:08:02.515Z","repository":{"id":57500883,"uuid":"147372876","full_name":"skx/deployr","owner":"skx","description":"A simple golang application to automate the deployment of software releases.","archived":false,"fork":false,"pushed_at":"2024-12-24T17:44:24.000Z","size":150,"stargazers_count":342,"open_issues_count":0,"forks_count":26,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-01T15:10:27.354Z","etag":null,"topics":["automation","deployment","devops","golang","scp","ssh","util"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"skx","custom":"https://steve.fi/donate/"}},"created_at":"2018-09-04T16:06:45.000Z","updated_at":"2025-02-19T19:25:19.000Z","dependencies_parsed_at":"2025-01-13T04:04:34.608Z","dependency_job_id":"6437f5b9-a595-4e4a-9454-4bf6e30a8816","html_url":"https://github.com/skx/deployr","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Fdeployr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Fdeployr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Fdeployr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Fdeployr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skx","download_url":"https://codeload.github.com/skx/deployr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247878022,"owners_count":21011158,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","deployment","devops","golang","scp","ssh","util"],"created_at":"2024-08-04T20:01:06.384Z","updated_at":"2025-04-08T16:08:02.472Z","avatar_url":"https://github.com/skx.png","language":"Go","readme":"[![Go Report Card](https://goreportcard.com/badge/github.com/skx/deployr)](https://goreportcard.com/report/github.com/skx/deployr)\n[![license](https://img.shields.io/github/license/skx/deployr.svg)](https://github.com/skx/deployr/blob/master/LICENSE)\n[![Release](https://img.shields.io/github/release/skx/deployr.svg)](https://github.com/skx/deployr/releases/latest)\n\n\n\nTable of Contents\n=================\n\n* [deployr](#deployr)\n* [Installation \u0026amp; Dependencies](#installation--dependencies)\n  * [Source Installation go \u0026lt;=  1.11](#source-installation-go---111)\n  * [Source installation go  \u0026gt;= 1.12](#source-installation-go---112)\n* [Overview](#overview)\n  * [Authentication](#authentication)\n  * [Examples](#examples)\n  * [File Globs](#file-globs)\n* [Variables](#variables)\n  * [Predefined Variables](#predefined-variables)\n* [Template Expansion](#template-expansion)\n* [Missing Primitives?](#missing-primitives)\n  * [Alternatives](#alternatives)\n* [Github Setup](#github-setup)\n\n\n# deployr\n\n`deployr` is a simple utility which is designed to allow you to easily automate simple application-deployment via SSH.\n\nThe core idea behind `deployr` is that installing (simple) software upon remote hosts frequently consists of a small number of steps:\n\n* Uploading a small number of files, for example:\n  * A binary application.\n  * A configuration-file.\n  * A systemd unit-file\n  * etc.\n* Running a small number of commands, some conditionally, for example:\n  * Enable the systemd unit-file.\n  * Start the service.\n\nThis is particularly true for golang-based applications which frequently consist of an single binary, a single configuration file, and an init-file to ensure the service can be controlled.\n\nIf you want to keep your deployment recipes automatable, and reproducible, then scripting them with a tool like this is ideal.  (Though you might prefer something more popular \u0026 featureful such as `ansible`, `fabric`, `salt`, etc.)\n\n\"Competing\" systems tend to offer more facilities, such as the ability to add Unix users, setup MySQL database, add cron-entries, etc.  Although it isn't impossible to do those things in `deployr` it is not as natural as other solutions.  (For example you can add a cron-entry by uploading a file to `/etc/cron.d/my-service`, or you can add a user via `Run adduser bob 2\u003e/dev/null`.)\n\nOne obvious facility that most similar systems, such as ansible, offer is the ability to perform looping operations, and comparisons.  We don't offer that and I'm not sure we ever will - even if we did add the ability to add cronjobs, etc.\n\nIn short think of this as an alternative to using a bash-script, which invokes scp/rsync/ssh.  It is not going to compete with ansible, or similar.  (Though it is reasonably close in spirit to `fabric` albeit with a smaller set of primitives.)\n\n\n\n## Installation \u0026 Dependencies\n\nThere are two ways to install this project from source, which depend on the version of the [go](https://golang.org/) version you're using.\n\n\n### Source Installation go \u003c=  1.11\n\nIf you're using `go` before 1.11 then the following command should fetch/update `deployr`, and install it upon your system:\n\n     $ go get -u github.com/skx/deployr\n\n### Source installation go  \u003e= 1.12\n\nIf you're using a more recent version of `go` (which is _highly_ recommended), you need to clone to a directory which is not present upon your `GOPATH`:\n\n    git clone https://github.com/skx/deployr\n    cd deployr\n    go install\n\n\nIf you don't have a golang environment setup you should be able to download a binary for GNU/Linux from [our release page](https://github.com/skx/deployr/releases).\n\n\n\n## Overview\n\n`deployr` has various sub-commands, the most useful is the `run` command which\nallows you to execute a recipe-file:\n\n    $ deployr run [options] recipe1 recipe2 .. recipeN\n\nEach specified recipe is parsed and the primitives inside them are then executed line by line.  The following primitives/commands are available:\n\n* `CopyFile local/path remote/path`\n  * Copy the specified local file to the specified path on the remote system.\n  * If the local \u0026 remote files were identical, such that no change was made, then this fact will be noted.\n  * See later note on globs.\n* `CopyTemplate local/path remote/path`\n  * Copy the specified local file to the specified path on the remote system, expanding variables prior to running the copy.\n  * If the local \u0026 remote files were identical, such that no change was made, then this fact will be noted.\n  * See later note on globs.\n* `DeployTo [user@]hostname[:port]`\n  * Specify the details of the host to connect to, this is useful if a particular recipe should only be applied against a single host.\n  * If you don't specify a target within your recipe itself you can instead pass it upon the command-line via the `-target` flag.\n* `IfChanged \"Command\"`\n  * The `CopyFile` and `CopyTemplate` primitives record whether they made a change to the remote system.\n  * The `IfChanged` primitive will execute the specified command if the previous copy-operation resulted in the remote system being changed.\n* `Run \"Command\"`\n  * Run the given command (unconditionally) upon the remote-host.\n* `Set name \"value\"`\n  * Set the variable \"name\" to have the value \"value\".\n  * Once set a variable can be used in the recipe, or as part of template-expansion.\n* `Sudo` may be added as a prefix to `Run` and `IfChanged`.\n  * If present this will ensure the specified command runs as `root`.\n  * The sudo example found beneath [examples/sudo/](examples/sudo/) demonstrates usage.\n\n\n\n### Authentication\n\nPublic-Key authentication is only supported mechanism for connecting to a remote host, or remote hosts.  There is zero support for authentication via passwords.\n\nBy default `~/.ssh/id_rsa` will be used as the key to connect with, but if you prefer you can specify a different private-key with the `-identity` flag to the run sub-command:\n\n    $ deployr run -identity ~/.ssh/host\n\nIn addition to using a key specified via the command-line deployr also supports the use of `ssh-agent`.  Simply set the environmental-variable `SSH_AUTH_SOCK` to the path of your agent's socket.\nOn Windows deployr supports `pageant`, which is a Windows-specific implementation of SSH Agent. If pageant is running, deployr will detect it and use it for authentication.\n\n\n\n### Examples\n\nThere are several examples included beneath [examples/](examples/), the shortest one [examples/simple/](examples/simple/) is a particularly good recipe to examine to get a feel for the system:\n\n    $ cd ./examples/simple/\n    $ deployr run -target [user@]host.example.com[:port] ./deployr.recipe\n\nFor more verbose output the `-verbose` flag may be added:\n\n    $ cd ./examples/simple/\n    $ deployr run -target [user@]host.example.com[:port] -verbose ./deployr.recipe\n\nSome other flags are also available, consult \"`deployr help run`\" for details.\n\n\n### File Globs\n\nBoth the `CopyFile` and `CopyTemplate` primitives allow the use of file-globs,\nwhich allows you to write a line like this:\n\n    CopyFile lib/systemd/system/* /lib/systemd/system/\n\nAssuming you have the following input this will copy all the files, as you\nwould expect:\n\n      ├── deploy.recipe\n      └── lib\n          └── systemd\n              └── system\n                  ├── overseer-enqueue.service\n                  ├── overseer-enqueue.timer\n                  ├── overseer-worker.service\n                  └── purppura-bridge.service\n\n**NOTE** That this wildcard support is _not_ the same as a recursive copy,\nthat is not supported.\n\nThe `IfChanged` primitive will regard a previous copy operation as having\nresulted in a change if any single file changes during the run of a copy\noperation that involves a glob.\n\n\n## Variables\n\nIt is often useful to allow values to be stored in variables, for example if you're used to pulling a file from a remote host you might make the version of that release a variable.\n\nVariables are defined with the `Set` primitive, which takes two arguments:\n\n* The name of the variable.\n* The value to set for that variable.\n  * Values will be set as strings, in fact our mini-language only understands strings.\n\nIn the following example we declare the variable called \"RELEASE\" to have the value \"1.2\", and then use it in a command-execution:\n\n    Set RELEASE \"1.2\"\n    Run \"wget -O /usr/local/bin/app-${RELEASE} \\\n           https://example.com/dist/app-${RELEASE}\"\n\nIt is possible to override the value of a particular variable via a command-line argument, for example:\n\n    $ deployr run --set \"ENVIRONMENT=PRODUCTION\" ...\n\nIf you do this any attempt to `Set` the variable inside the recipe itself will be silently ignored.  (i.e. A variable which is set on the command-line will become essentially read-only.) This is useful if you have a recipe where the only real difference is the set of configuration files, and the destination host. For example you could write all your copies like so:\n\n    #\n    # Lack of recursive copy is a pain here.\n    # See:\n    #   https://github.com/skx/deployr/issues/6\n    #\n    CopyFile files/${ENVIRONMENT}/etc/apache2.conf /etc/apache2/conf\n    CopyFile files/${ENVIRONMENT}/etc/redis.conf   /etc/redis/redis.conf\n    ..\n\nThen have a tree of files:\n\n      ├── files\n          ├── development\n          │   ├── apache2.conf\n          │   └── redis.conf\n          └── production\n              ├── apache2.conf\n              └── redis.conf\n\nAnother case where this come in handy is when dealing the secrets. Pass your secrets via command-line arguments instead of setting them in the recipe so you don't commit them by mistake, for example:\n\n        $ deployr run --set \"API_KEY=foobar\" ...\n\nThen use the `API_KEY`:\n\n        Run \"curl api.example.com/releases/latest -H 'Authorization: Bearer ${API_KEY}'\"\n\nIn a CI environnement, use command-line arguments to retrieve environnement variables available in the CI.\n\n        $ deployr run --set \"RELEASE=$CI_COMMIT_TAG\" ...\n\n### Predefined Variables\n\nThe following variables are defined by default:\n\n* `host`\n  * The host being deployed to.\n* `now`\n  * An instance of the golang [time](https://golang.org/pkg/time/) object.\n* `port`\n  * The port used to connect to the remote host (22 by default).\n* `user`\n  * The username we login to the remote host as (root by default).\n\n\n\n## Template Expansion\n\nIn addition to copying files literally from the local system to the remote\nhost it is also possible perform some limited template-expansion.\n\nTo copy a file literally you'd use the `CopyFile` primitive which copies the\nfile with no regards to the contents (handling binary content):\n\n    CopyFile local.txt /tmp/remote.txt\n\nTo copy a file with template-expansion you should use the `CopyTemplate` primitive instead:\n\n    CopyTemplate local.txt /tmp/remote.txt\n\nThe file being copied will then be processed with the `text/template` library\nwhich means you can access values like so:\n\n    #\n    # This is a configuration file blah.conf\n    # We can expand variables like so:\n    #\n    # Deployed version {{get \"RELEASE\"}} on Host:{{get \"host\"}}:{{get \"port\"}}\n    # at {{now.UTC.Day}} {{now.UTC.Month}} {{now.UTC.Year}}\n    #\n\nIn short you write `{{get \"variable-name-here\"}}` and the value of the variable\nwill be output inline.\n\nAny variable defined with `Set` (or via a command-line argument) will be available to you, as well as the\n[predefined variables](#predefined-variables) noted above.\n\n\n\n## Missing Primitives?\n\nIf there are primitives you think would be useful to add then please do\n[file a bug](http://github.com/skx/deployr/issues).\n\n\n### Alternatives\n\nThere are many alternatives to this simple approach.  The most obvious two\nwould be:\n\n* [ansible](https://www.ansible.com/)\n  * Uses YAML to let you run commands on multiple remote hosts via SSH.\n  * Very featureful, but also a bit hard to be readable due to the YAML use.\n* [fabric](http://www.fabfile.org/)\n  * Another Python-based project, which defines some simple primitive functions such as `run` and `put` to run commands, and upload files respectively.\n\nAs a very simple alternative I put together [marionette](https://github.com/skx/marionette/) which allows running commands, and setting file-content, but this works on the __local__ system only - no SSH involved.\n\nFor large-scale deployments you'll probably want to consider Puppet, Chef, or something more established and powerful.  Still this system has its place.\n\n\n\n## Github Setup\n\nThis repository is configured to run tests upon every commit, and when\npull-requests are created/updated.  The testing is carried out via\n[.github/run-tests.sh](.github/run-tests.sh) which is used by the\n[github-action-tester](https://github.com/skx/github-action-tester) action.\n\nReleases are automated in a similar fashion via [.github/build](.github/build),\nand the [github-action-publish-binaries](https://github.com/skx/github-action-publish-binaries) action.\n\nSteve\n--\n","funding_links":["https://github.com/sponsors/skx","https://steve.fi/donate/"],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskx%2Fdeployr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskx%2Fdeployr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskx%2Fdeployr/lists"}