{"id":13591446,"url":"https://github.com/pioz/god","last_synced_at":"2025-10-13T19:34:18.929Z","repository":{"id":44088011,"uuid":"496110574","full_name":"pioz/god","owner":"pioz","description":"Automation tool to deploy and manage Go services using systemd on GNU/Linux machines","archived":false,"fork":false,"pushed_at":"2025-08-13T16:04:05.000Z","size":200,"stargazers_count":247,"open_issues_count":2,"forks_count":13,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-10-13T19:34:17.336Z","etag":null,"topics":["deployment","golang","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/pioz.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-25T06:33:03.000Z","updated_at":"2025-09-26T22:56:11.000Z","dependencies_parsed_at":"2024-06-18T21:52:55.704Z","dependency_job_id":null,"html_url":"https://github.com/pioz/god","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/pioz/god","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pioz%2Fgod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pioz%2Fgod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pioz%2Fgod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pioz%2Fgod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pioz","download_url":"https://codeload.github.com/pioz/god/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pioz%2Fgod/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279016918,"owners_count":26085888,"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","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","golang","tool"],"created_at":"2024-08-01T16:00:57.682Z","updated_at":"2025-10-13T19:34:18.896Z","avatar_url":"https://github.com/pioz.png","language":"Go","readme":"# God - Go-daemons\n\nGod (go-daemons) is a tool to deploy and manage daemons in the Go ecosystem on GNU/Linux machines\nusing [systemd](https://www.freedesktop.org/wiki/Software/systemd/).\n\n\u003cimg src=\"gopher/devil_gopher.png\" width=\"300\" alt=\"Devil Gopher\" /\u003e\n\nGod installs your go binary in the remote machine (server) using `go install`,\ncreate the systemd unit file (.service file) and allows you to\nstart/stop/restart the process.\n\n## Use case\n\nI often write small micro-services or web-services in Go, and I need to deploy\nthe service on a server in an easy and fast way, without bothering! Usually I\ncompile the executable for the server architecture, log in via SSH on the\nserver, copy the binary, create the configuration file for the new systemd\nservice, install it and start the process. A series of commands that are always\nthe same but that I forget every time and have to look in my notes somewhere.\nAnd that's not all: when I make a change to my program, then I have to recompile\nit, log in via SSH on the server, copy the binary and restart the service. A\nreal waste of time!\n\nSo I decided to write God, a tool written in Go. With God I can quickly and\neasily deploy and manage one or more services written in Go comfortably from my\nlaptop, without logging into the server via SSH using a simple\n[YAML](https://yaml.org/) configuration file.\n\n## Install God\n\n```\ngo install github.com/pioz/god@latest\ngod -h\n```\n\n## Usage\n\n📒 **To read the list of all commands and options run `god -h`**.\n\nGod uses a simple YAML file like this one to understand what to do:\n\n```yaml\nmy_service_name1:\n  user: pioz\n  host: 119.178.21.21\n  go_install: github.com/pioz/go_hello_world_server@latest\nmy_service_name2:\n  user: pioz\n  host: 119.178.21.22\n  go_install: github.com/pioz/go_hello_world_server2@latest\n```\n\nYou can install a new service on a remote server with the following command:\n\n```\ngod -f conf/file.yml install my_service_name1\n```\n\nIf you omit the `-f` option, God will try to find the conf file in `.god.yml`\npath.\n\nNow, what happens?\n\nGod will try to connect via SSH to the server `119.178.21.21` with the user\n`pioz` on the default SSH port 22 using the private key stored locally in\n`~/.ssh/id_rsa`. Currently, only authentication via private key is supported and\nauthentication via plain password is not planned. Then perform this sequence of\ncommands:\n\n1. Check if Go is installed on the remote host\n2. Check if systemd is installed on the remote host\n3. Check if the user `pioz` is in the [lingering list](https://www.freedesktop.org/software/systemd/man/loginctl.html)\n4. Install the Go package `github.com/pioz/go_hello_world_server@latest` in `$GOBIN` (default `$GOBIN`)\n5. Create the systemd unit service file in `~/.config/systemd/user/`\n6. Reload systemd daemon with `systemctl --user daemon-reload`\n7. Enable the new service with `systemctl --user enable my_service_name1`\n\nThe systemd unit service file will be saved in\n`~/.config/systemd/user/my_service_name1.service` and its content is\nsomething like this:\n\n```\n[Unit]\nDescription=my_service_name1\n\n[Service]\nType=simple\nRestart=always\nWorkingDirectory=/home/pioz\nExecStart=/home/pioz/go/bin/go_hello_world_server\n\n[Install]\nWantedBy=default.target\n```\n\nNow you can start the service with\n\n```\ngod start my_service_name1\n```\n\nthat will run in the remote host\n\n```\nsystemctl --user start my_service_name1\n```\n\nIf you want rollback and clean your server you can uninstall the service with\n`god uninstall my_service_name1`.\n\n### Install from private repository\n\nIf your Go service package is located in a private repository, God allows the\nremote server to access the repository prepending in the remote\n[`~/.netrc`](https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html)\nfile the login information that you can specify on the God YAML configuration\nfile (read `god -h` for more details). An example here:\n\n```yaml\nmy_private_service:\n  user: pioz\n  host: 119.178.21.21\n  go_install: github.com/pioz/go_hello_world_server_private@latest\n  # Private repo access\n  go_private: github.com/pioz/go_hello_world_server_private\n  netrc_machine: github.com\n  netrc_login: githublogin@gmail.com\n  netrc_password: youRgithubAcce$$tok3n\n```\n\n### Override YAML configuration options with env variables\n\nAll configuration options that you can specify in the `.god.yml` file can be\noverridden with environment variables in the form\n`\u003cSERVICE_NAME\u003e_\u003cOPTION_NAME\u003e`. For example, the option `netrc_password` can be\noverridden with the environment variable `MY_PRIVATE_SERVICE_NETRC_PASSWORD`.\nThis is really useful if you want to avoid storing sensitive data in the\n`.god.yml` file.\n\nSo you can install your private service with this command:\n\n```\nMY_PRIVATE_SERVICE_NETRC_PASSWORD=youRgithubAcce$$tok3n god install\n```\n\nNotice that God uses [this\nfunction](https://github.com/pioz/god/blob/c6d5e174596d584d348f4c74b69086c13533a01f/runner/runner.go#L282)\nto convert the service name in the environment variable. So all characters not\nin `[A-Za-z0-9_]` will be replaced by an underscore.\n\n### Manage multiple services at the same time\n\nIf you do not specify a service name, all services defined in the YAML file will\nbe taken into consideration, for example if you run `god restart` it will\nrestart all services defined in the YAML file in parallel. 🤩\n\nThis is really useful if your infrastructure is made by many microservices.\n\n### Copy files\n\nIf you need to upload files to the remote working directory you can use the\nconfiguration options `copy_files` in the YAML conf file. For example you can\nupload a `.env` file needed by your service.\n\n```yaml\nmy_service_name:\n  user: pioz\n  host: 119.178.21.21\n  go_install: github.com/pioz/go_hello_world_server@latest\n  copy_files:\n    - .env\n    - WARNING.txt\n    - /home/pioz/icons/\n```\n\n### Help\n\n```\ngod -h\nUsage: god [OPTIONS...] {COMMAND} ...\n  -c\tCreates the remote service working directory if not exists. With uninstall command, removes log files and the remote working directory if empty.\n  -f string\n    \tConfiguration YAML file path. (default \".god.yml\")\n  -h\tPrint this help.\n  -q\tDisable printing.\n\nCommands:\nAfter each command you can specify one or more services. If you do not specify any, all services in the YAML\nconfiguration file will be selected.\n\ninstall SERVICE...            Install one or more services on the remote host.\nuninstall SERVICE...          Uninstall one or more services on the remote host.\nstart SERVICE...              Start one or more services.\nstop SERVICE...               Stop one or more services.\nrestart SERVICE...            Restart one or more services.\nstatus SERVICE...             Show runtime status of one or more services.\nshow-service SERVICE...       Print systemd unit service file of one or more services.\n\nConfiguration YAML file options:\nuser                          User to log in with on the remote machine. (default current user)\nhost                          Hostname to log in for executing commands on the remote host. (required)\nport                          Port to connect to on the remote host. (default 22)\nprivate_key_path              Local path of the private key used to authenticate on the remote host. (default\n                              '~/.ssh/id_rsa')\ngo_exec_path                  Remote path of the Go binary executable. (default '$GOBIN/go')\ngo_bin_directory              The directory where 'go install' will install the service executable. (default\n                              '$GOBIN')\ngo_install                    Go package to install on the remote host. Package path must refer to main packages and\n                              must have the version suffix, ex: @latest. (required)\ngo_private                    Set GOPRIVATE environment variable to be used when run 'go install' to install from\n                              private sources.\nnetrc_machine                 Add in remote .netrc file the machine name to be used to access private repository.\nnetrc_login                   Add in remote .netrc file the login name to be used to access private repository.\nnetrc_password                Add in remote .netrc file the password or access token to be used to access private\n                              repository.\nsystemd_path                  Remote path of systemd binary executable. (default 'systemd')\nsystemd_services_directory    Remote directory where to save user instance systemd unit service configuration file.\n                              (default '~/.config/systemd/user/')\nsystemd_linger_directory      Remote directory where to find the lingering user list. If lingering is enabled for a\n                              specific user, a user manager is spawned for the user at boot and kept around after\n                              logouts. (default '/var/lib/systemd/linger/')\nexec_start                    Command with its arguments that are executed when this service is started.\nworking_directory             Sets the remote working directory for executed processes. (default: '~/')\nenvironment                   Sets environment variables for executed process. Takes a space-separated list of variable\n                              assignments.\nlog_path                      Sets the remote file path where executed processes will redirect its standard output and\n                              standard error.\nrun_after_service             Ensures that the service is started after the listed unit finished starting up.\nstart_limit_burst             Configure service start rate limiting. Services which are started more than burst times\n                              within an interval time interval are not permitted to start any more. Use\n                              'start_limit_interval_sec' to configure the checking interval.\nstart_limit_interval_sec      Configure the checking interval used by 'start_limit_burst'.\nrestart_sec                   Configures the time to sleep before restarting a service. Takes a unit-less value in\n                              seconds.\ncopy_files                    [Array] Copy files to the remote working directory.\nignore                        If a command is called without any service name, all services in the YAML configuration\n                              file will be selected, except those with ignore set to true. (default false)\n\nAll previous configuration options can be overridden with environment variables in the form\n\u003cSERVICE_NAME\u003e_\u003cOPTION_NAME\u003e. For example, the option netrc_password can be overridden with the environment variable\nMY_SERVICE_NAME_NETRC_PASSWORD.\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/pioz/god/issues.\n\n## License\n\nThe package is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpioz%2Fgod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpioz%2Fgod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpioz%2Fgod/lists"}