{"id":17032355,"url":"https://github.com/bom-d-van/harp","last_synced_at":"2025-03-17T10:34:04.784Z","repository":{"id":26005560,"uuid":"29448115","full_name":"bom-d-van/harp","owner":"bom-d-van","description":"A Go application deployment tool.","archived":false,"fork":false,"pushed_at":"2016-11-18T14:02:09.000Z","size":2181,"stargazers_count":266,"open_issues_count":1,"forks_count":16,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-16T10:51:15.506Z","etag":null,"topics":["deployment","go","tool"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bom-d-van.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-19T01:29:19.000Z","updated_at":"2025-03-04T10:41:14.000Z","dependencies_parsed_at":"2022-08-24T03:00:44.585Z","dependency_job_id":null,"html_url":"https://github.com/bom-d-van/harp","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bom-d-van%2Fharp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bom-d-van%2Fharp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bom-d-van%2Fharp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bom-d-van%2Fharp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bom-d-van","download_url":"https://codeload.github.com/bom-d-van/harp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244017070,"owners_count":20384266,"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":["deployment","go","tool"],"created_at":"2024-10-14T08:28:10.558Z","updated_at":"2025-03-17T10:34:04.044Z","avatar_url":"https://github.com/bom-d-van.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# harp\n\nHarp mades Go application deployment simpler. The strategy is binary deployment. It manages logs, restart, kill, rollback, and migrations of Go applications. Harp is made to run on local environment for small to middle-sized projects. Run harp on a dedicated build server is also viable.\n\n## What harp does\n\nHarp simply builds your application and upload it to your server. It brings you a complete solution for deploying common applications. It syncs, restarts, kills, and deploys your applications.\n\nThe best way to learn what harp does and helps is to use it. (In test directory, there are docker files and harp configurations you can play with)\n\n## System requirements\n\nLocal: Harps works on Mac OS X, Linux, Windows isn't tested.\n\nServer: Harps works on Linux servers.\n\nThird-party requirements: tar, rsync on both server and local.\n\n### Server access using SSH\n\nHarp is using passwordless login with ssh-agent to access your servers. You can find some help from here:\n\nhttp://www.linuxproblem.org/art_9.html\n\nYou can add your key in ssh-agent by:\n\n```sh\nssh-add ~/.ssh/id_rsa # or other path to your private key\nssh-add -l\n```\n\n## Examples\n\n```sh\n# Init harp.json\nharp init\n\n# Configure your servers and apps in harp.json. see section Configuration below.\nharp -s dev deploy\n\n# Or\nharp -s prod deploy\n\n# Restart server\nharp -s prod restart\n\n# Shut down server\nharp -s prod kill\n\n# Inspect server build info\nharp -s prod info\n\n# Rollback release\nharp -s prod rollback $version-tag\n\n# Tail server logs\nharp -s prod log\n\n# Specify config files\nharp -s prod -c config/harp.json deploy\n\n# Upload builds/migrations without executing it immediately\nharp -s prod -no-run deploy\n# Or shorter\nharp -s prod -nr deploy\n\n# Skip builds\nharp -s prod -no-build deploy\n\n# Skip file uploads\nharp -s prod -no-files deploy\n\n# More flags and usages\nharp -h\n\n# Run arbitrary Go program wihtout harp.json\nharp -server app@test.com:8022 -t run app.go # with default -goos=linux -goarch=amd64\n\n# Run shell commands or execute scripts with harp console (alias: sh, shell)\nharp -s prod console\nharp -s prod console \u003c my-shell-script\nharp -s prod console \u003c\u003c\u003c(ls)\n```\n\n## Common Trouble Shootings\n\n### Too many open files\n\nTo fix this problem, you need to increase ulimit:\n\n```\nulimit -n 10240 // or any number that is large enough\n```\n\n### The .harp directory\n\nHarp creates a temporary directory called .harp in the current path where it is invoked. It will be removed after harp exits. Under rare circumstances, you can use `harp clean` to remove the directory manually. Also, it's better include `.harp` in `.gitignore` or similar counterpart of your VCS tool.\n\n## Configuration\n\nexample:\n\n```js\n{\n\t// comments are supported in harp.json\n\t\"GOOS\": \"linux\",   // for go build\n\t\"GOARCH\": \"amd64\", // for go build\n\t\"App\": {\n\t\t\"Name\":       \"app\",\n\t\t\"ImportPath\": \"github.com/bom-d-van/harp/test\",\n\n\t\t// will be applied to all servers\n\t\t\"Envs\": {\n\t\t\t\"var1\": \"value\"\n\t\t},\n\n\t\t// these are included in all file Excludeds\n\t\t\"DefaultExcludeds\": [\".git/\", \"tmp/\", \".DS_Store\", \"node_modules/\", \"*.go\"],\n\t\t\"Files\":      [\n\t\t\t// files here could be a string or an object\n\t\t\t\"github.com/bom-d-van/harp/test/files\",\n\t\t\t{\n\t\t\t\t\"Path\": \"github.com/bom-d-van/harp/test/file\",\n\t\t\t\t\"Excludeds\": [\"builds\"]\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"Path\": \"github.com/bom-d-van/harp/test/file2\",\n\t\t\t\t// These option will enable rsync --delete during deploy\n\t\t\t\t// You can check the effect with `harp inspect deploy`\n\t\t\t\t// Need to be careful with this option.\n\t\t\t\t//\n\t\t\t\t// Because it may cause some wanted results, so it's\n\t\t\t\t// disabled by default\n\t\t\t\t\"Delete\": true\n\t\t\t}\n\t\t]\n\t},\n\t\"Servers\": {\n\t\t\"prod\": [{\n\t\t\t\"ID\":  \"pluto\", // ID field could be used to specify server with `-server` flag\n\t\t\t\"User\": \"app\",\n\t\t\t// server specific env vars\n\t\t\t\"Envs\": {\n\t\t\t\t\"var2\": \"value2\"\n\t\t\t},\n\t\t\t\"Host\": \"192.168.59.103\",\n\t\t\t\"Port\": \":49155\"\n\t\t}, {\n\t\t\t\"User\": \"app\",\n\t\t\t\"Host\": \"192.168.59.104\",\n\t\t\t\"Port\": \":49156\"\n\t\t}],\n\n\t\t\"dev\": [{\n\t\t\t\"User\": \"app\",\n\t\t\t\"Host\": \"192.168.59.102\",\n\t\t\t\"Port\": \":49155\"\n\t\t}]\n\t}\n}\n```\n\n### Vendor Support\n\n`harp` doesn't have built-in vendor support. To upload vendor files, you could still use its import path releative to your $GOPATH. e.g.:\n\n```\n\t\"Files\": [\n\t\t\"github.com/org/repo/vendor/my/pkg\",\n\t\t...\n\t]\n```\n\n## Usages\n\n### How to specify server or server sets:\n\nUsing the configuration above as example, server set means the key in `Servers` object value, i.e. `prod`, `dev`.\nWhile server is elemnt in server set arrays, you can specify it by `{User}@{Host}{Port}`.\n\n```sh\n# deploy prod servers\nharp -s prod deploy\n\n# deploy dev servers\nharp -s dev deploy\n\n# deploy only one prod server:\nharp -server app@192.168.59.102:49155 deploy\n```\n\n### Migration / Run a Go package/file on remote server\n\nYou can specify server or server sets on which your migration need to be executed.\n\nSimple:\n\n```\nharp -server app@192.168.59.103:49153 run migration.go\n```\n\nWith env and arguments:\n\n```\nharp -server app@192.168.59.103:49153 run \"AppEnv=prod migration2.go -arg1 val1 -arg2 val2\"\n```\n\nMultiple migrations:\n\n```\nharp -server app@192.168.59.103:49153 run migration.go \"AppEnv=prod migration2.go -arg1 val1 -arg2 val2\"\n```\n\n__Note__: Harp saved the current migration files in `$HOME/harp/{{.App.Name}}/migrations.tar.gz`. You can uncompress it and execute the binary manually if you prefer or on special occasions.\n\n### Rollback\n\nBy default harp will save three most recent releases in `$HOME/harp/{{.App.Name}}/releases` directory. The current release is the newest release in the releases list.\n\n```\n# list all releases\nharp -s prod rollback ls\n\n# rollback\nharp -s prod rollback 15-06-14-11:29:14\n```\n\nAnd there is also a `rollback.sh` script in `$HOME/harp/{{.App.Name}}` that you can use to rollback release.\n\nYou can change how many releases you want to keep by `RollbackCount` or disable rollback by `NoRollback` in harp file.\n\n```\n{\n\t\"GOOS\": \"linux\",   // for go build\n\t\"GOARCH\": \"amd64\", // for go build\n\n\t\"NoRollback\": true,\n\t\"RollbackCount\": 10,\n\n\t\"App\": {\n\t\t...\n\t},\n\t...\n}\n```\n\nNote: rollback depends on `harp.json`, if `Files` or other configs are changed, rollback might not work.\n\n### Build Args Specification\n\nHarp supports go build tool arguments specification.\n\n```\n\"App\": {\n\t\"Name\":       \"app\",\n\t\"BuildArgs\":  \"-tags daemon\"\n}\n```\n\nYou can also override or ad-hoc specify build args from command line as follows:\n\n```\nharp -s prod -build-args '-tags client' deploy\n```\n\nNote: currently migration using build args from cli are not supported yet.\n\n### Build Override\n\nHarp allows you to override default build command.\n\nAdd `BuildCmd` option in `App` as bellow:\n\n```\n\"App\": {\n\t\"Name\":       \"app\",\n\t\"BuildCmd\":   \"docker run -t -v $GOPATH:/home/app golang  /bin/sh -c 'cd /home/app/src/github.com/bom-d-van/harp; GOPATH=/home/app /usr/local/go/bin/go build -o /home/app/src/github.com/bom-d-van/harp/%s %s'\"\n}\n```\n\nThe first `%s` represents the harp temporary output, and the second `%s` represents a import path or a file path for some migrations. An example output in `test/harp2.json` is:\n\n```sh\n# for normal builds\ndocker run -t -v $GOPATH:/home/app golang  /bin/sh -c 'GOPATH=/home/app /usr/local/go/bin/go build -o \\$GOPATH/src/github.com/bom-d-van/harp/.harp/app github.com/bom-d-van/harp/test'\n\n# for migrations/runs\ndocker run -t -v $GOPATH:/home/app golang  /bin/sh -c 'GOPATH=/home/app /usr/local/go/bin/go build -o \\$GOPATH/src/github.com/bom-d-van/harp/.harp/migrations/migration3.go github.com/bom-d-van/harp/test/migration3'\n```\n\n__NOTE:__ Build override doesn't support non-package migrations. i.e. every migration under build override has to be a legal Go package.\n\nBuild override is useful doing cross compilation for cgo-involved projects, e.g. using Mac OS X building Linux binaries by docker or any other tools etc.\n\nNote: Harps is saving temporary build output and files in `$(pwd)/.harp`. Therefore harp expects build output appears in directory `$(pwd)/.harp/{{app name}}` where you evoke harp command (i.e. pwd). And `$(pwd)/.harp/migrations/{{migration name}}` for migrations.\n\n### Script Override\n\nharp supports you to override its default deploy script. Add configuration like bellow:\n\n```\n\"App\": {\n\t\"Name\":         \"app\",\n\t\"DeployScript\": \"path-to-your-script-template\",\n\t\"RestartScript\": \"path-to-your-script-template\",\n\t\"MigrationScript\": \"path-to-your-script-template\"\n},\n```\n\n#### Deploy and Restart Script\n\nThe script could be a `text/template.Template`, into which harp pass a data as bellow:\n\n```\nmap[string]interface{}{\n\t\"App\":           harp.App,\n\t\"Server\":        harp.Server,\n\t\"SyncFiles\":     syncFilesScript,\n\t\"RestartServer\": restartScript,\n}\n\ntype App struct {\n\tName       string\n\tImportPath string\n\n\tNoRelMatch       bool\n\tDefaultExcludeds []string\n\tFiles            []File\n\n\tArgs []string\n\tEnvs map[string]string\n\n\tBuildCmd  string\n\tBuildArgs string\n\n\tKillSig string\n\n\t// Default: 1MB\n\tFileWarningSize int64\n\n\tDeployScript  string\n\tRestartScript string\n}\n\ntype Server struct {\n\tID string\n\n\tEnvs   map[string]string\n\tHome   string\n\tGoPath string\n\tLogDir string\n\n\tUser string\n\tHost string\n\tPort string\n\n\tSet string // aka, Type\n\n\tclient *ssh.Client\n\n\tConfig *Config\n\n\t// Proxy is for ssh bastion host/ProxyCommand/middleman\n\tProxy *Server\n}\n\nfunc (Server) AppRoot() string\n```\n\nA default deploy script is:\n\n```\nset -e\n{{.SyncFiles}}\n{{.SaveRelease}}\n{{.RestartServer}}\n```\n\nSimilarly, restart script could be override too. And its default template is:\n\n```\nset -e\n{{.RestartServer}}\n```\n\nYou can inspect your script by evoking command: `harp -s prod inspect deploy` or `harp -s prod inspect restart`.\n\n#### Migration Script\n\nMigration script template data is:\n\n```\nmap[string]interface{}{\n\t\"Server\":        harp.Server,\n\t\"App\":           harp.App,\n\t\"DefaultScript\": string,\n}\n```\n\nThe default migration template contains only the default script. So for now you can only rewrite migration in this fashion:\n\n```\nset -e\n\n# custom scripts\n\n{{.DefaultScript}}\n\n# custom scripts\n```\n\n### Server Informations\n\nYou can use `harp info` to retrieve build and deploy information about the current running server. For example:\n\n```sh\nharp info\n\n===== app@192.168.59.103:49153\nGo Version: go version go1.4.2 darwin/amd64\nGOOS: linux\nGOARCH: amd64\nGit Checksum: f8eb715f33c36d8ec018fe116491a01540106fc8\nComposer: bom_d_van\nBuild At: 2015-07-06 21:28:55.359181899 +0800 CST\n\n```\n\nNote: Composer means deployer.\n\nYou can specify your composer name by saving your name in a file named `.harp-composer`.\n\n### Scripts saved on servers\n\nHarp saves a few scripts on yoru servers after deploy. It could be found in `$HOME/harp/$APP_Name/`.\n\nThese scripts could be used as Monitor integration:\n\n* `kill.sh`: kill the application;\n* `restart.sh`: restart the application;\n* `rollback.sh`: rollback the application: need to specify version (directory names in `releases` folder).\n\n### Initialize Go cross compilation (For Go \u003c= 1.5)\n\nIf you need to initialize cross compilation environment, harp has a simple commend to help you:\n\n```\nharp xc\n```\n\nNote: before using `harp xc`, you need to enable cross compilation by installing go from source, details could be found here: https://golang.org/doc/install/source\n\n### Console (sh, shell)\n\nRun shell commands or execute scripts with harp console (alias: sh, shell)\n\n```\n# start a repl to execute shell commands\nharp -s prod console\n\n# run a script\nharp -s prod console \u003c my-shell-script\n\n# another example\nharp -s prod console \u003c\u003c\u003c(ls)\n```\n\nNote: harp console doesn't support blocking calls like `tail -f file.log`.\n\n### Deployment history\n\nharp saves a one-line deployment/restart/kill/rollback log in `~/harp/$APP_Name/log/history.log`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbom-d-van%2Fharp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbom-d-van%2Fharp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbom-d-van%2Fharp/lists"}