{"id":13895749,"url":"https://github.com/leafo/lapis-systemd","last_synced_at":"2025-05-12T20:39:12.760Z","repository":{"id":48323560,"uuid":"44729803","full_name":"leafo/lapis-systemd","owner":"leafo","description":"systemd integration for lapis","archived":false,"fork":false,"pushed_at":"2024-04-11T20:31:47.000Z","size":39,"stargazers_count":18,"open_issues_count":3,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-20T17:39:46.661Z","etag":null,"topics":["lapis","lua","moonscript","systemd"],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leafo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2015-10-22T07:42:34.000Z","updated_at":"2024-08-12T10:06:20.000Z","dependencies_parsed_at":"2024-04-11T20:25:51.860Z","dependency_job_id":"8884ca93-e682-4ab2-b2be-d178c363edd1","html_url":"https://github.com/leafo/lapis-systemd","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leafo%2Flapis-systemd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leafo%2Flapis-systemd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leafo%2Flapis-systemd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leafo%2Flapis-systemd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leafo","download_url":"https://codeload.github.com/leafo/lapis-systemd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253817615,"owners_count":21969009,"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":["lapis","lua","moonscript","systemd"],"created_at":"2024-08-06T18:02:26.681Z","updated_at":"2025-05-12T20:39:12.733Z","avatar_url":"https://github.com/leafo.png","language":"Lua","readme":"# lapis-systemd\n\n`lapis-systemd` is a Lapis extension that lets you create `systemd` service\nfiles for your Lapis applications. It also provides a minimal module to work\nwith the systemd journal.\n\n## Install\n\n```\n$ luarocks install lapis-systemd\n```\n\n## Usage\n\n\n```bash\n$ lapis systemd service --help\nUsage: lapis systemd service ([--install] | [--print]) [-h]\n       [\u003cenvironment\u003e]\n\nGenerate service file\n\nArguments:\n   environment           Environment to generate service file for (overrides --environment)\n\nOptions:\n   -h, --help            Show this help message and exit.\n   --install             Installs the service file to the system, requires sudo permission\n   --print, -p           Print the service file to stdout instead of writing it\n```\n\n## Creating service files\n\nThe `service` command generates service files based on the environment\nconfiguration. From your shell:\n\n```bash\n$ lapis systemd service development\n```\n\nWill generate a file in the current directory, named after your app:\n`some-app-development.service`\n\nThe contents might look like this:\n\n```ini\n[Unit]\nDescription=some-app development\nAfter=network.target\n\n[Service]\nType=simple\nPIDFile=/home/leafo/code/sites/itch.io/logs/nginx.pid\nEnvironment='PATH=/home/leafo/.luarocks/bin:/usr/bin' 'LUA_PATH=;;/home/leafo/.luarocks/share/lua/5.1/?.lua;/home/leafo/.luarocks/share/lua/5.1/?/init.lua' 'LUA_CPATH=;;/home/leafo/.luarocks/lib/lua/5.1/?.so'\nWorkingDirectory=/home/leafo/code/sites/itch.io\nExecStart=/home/leafo/.luarocks/bin/lapis server development\nExecReload=/home/leafo/.luarocks/bin/lapis build development\n\n[Install]\nWantedBy=multi-user.target\n```\n\nBy default, service command will copy certain environment variables from the\ncurrent shell and embed them directly into the service file. This ensures that\nLapis is run as if you had launched it directly from your shell. The following\nenvironment variables are embedded by default:\n\n- `PATH`\n- `LUA_PATH`\n- `LUA_CPATH`\n\nBecause of these hard-coded paths, it is not recommended to check the generated\nservice files into your repository. If you ever move the project or reconfigure\nyour system, you should regenerate the service file.\n\nYou can generate and install the service file to the system using the following\ncommand:\n\n```bash\n$ lapis systemd service development --install\n```\n\n**Do not run this command with sudo, as it will invoke sudo for you when\ncopying the necessary file. Executing it with sudo could result in a service\nfile with incorrect environment variables embedded**\n\nYou can then start your service:\n\n```bash\n$ sudo systemctl start some-app-development\n```\n\nAnd view the logs for it:\n\n```bash\n$ sudo journal -u some-app-development\n```\n\n### Configuring service file\n\nThe service file is configured from the `systemd` block within your Lapis\nconfiguration. This simplifies the generation of a service file based on the\nenvironment using a single, consistent command.\n\n### `user`\n\nThe `user` option specifies the user under which the service will run. This can\nbe particularly useful if you need the service to have specific permissions\nthat are associated with a certain user.\n\nIf the `user` option is not provided,  the service will not specify a user will\nrun under the default user of the system.\n\nIn the configuration example below, the service will run as the user \"leafo\".\n\n```lua\n-- config.lua\nlocal config = require(\"lapis.config\")\n\nconfig(\"production\", {\n  systemd = {\n    user = \"leafo\" -- service will run as user\n  }\n})\n```\n\nIf `user` is set to `true`, the name of the current user will be used. Note\nthat the user is embedded into the service file at the time of its creation and\nis not dynamically determined at runtime. The user is determined via `whoami`\nat the time of the service file's generation.\n\n### `env`\n\nThe `env` option allows you specify the environment variables for the service.\nThe value of `env` can either be a string, a table, or a boolean.\n\nBy default systemd service files have a minimal `PATH` and no other environment\nvariables set. Any environment variables that are needed by your application\nshould be assigned in the service file.\n\nIf `env` is not set, it will default to copying the environment variables\n`\"PATH\", \"LUA_PATH\", \"LUA_CPATH\"`. To avoid this default behavior set `env` to\nfalse to skip setting environment variables in the service file, or manually\nspecify the value:\n\nIf `env` is a table, it can contain two types of entries, each representing how\nto set the environment variable:\n\n- Array entries: These are treated as names of environment variables that\n  should be copied from the current shell environment.\n- Key-value pairs: These represent environment variables that should be set\n  directly, with the key as the variable name and the value as the variable\n  value.\n\n(If `env` is a string, it is considered used as a single name of the environment variable to copy)\n\nFor example:\n\nIf you want to set the environment variable `PORT` to `8080` and copy the\nenvironment variable `DATABASE_URL`, you could use the following configuration:\n\n```lua\n-- config.lua\nlocal config = require(\"lapis.config\")\n\nconfig(\"production\", {\n  systemd = {\n    env = {\n      PORT = 8080,\n      \"DATABASE_URL\"\n    }\n  }\n})\n```\n### `name`\n\nThe `name` option allowed for manual control of the name of the systemd\nservice.\n\nIf not set, the name is auto-generated from the last part of the current\ndirectory name. For example, `/home/user/my-app` would default to `my-app`.\n\n### `dir`\n\nThe `dir` option sets the service's working directory. If not set, it defaults\nto the directory at the service file's generation time using `pwd`.\n\n### `lapis_bin`\n\nThe `lapis_bin` option sets the location of the Lapis executable. If not set,\nit defaults to the location returned by the command `which lapis`.\n\n## Writing to logs\n\nYou can access the systemd journal with the `lapis.systemd.journal` module:\n\n```lua\njournal = require(\"lapis.systemd.journal\")\njournal.log(\"hello world!\", {priority = 5})\n```\n\nNote this will only work if the `journal` config option is set to a truthy value.\n\n### Journal Configuration\n\nThe log method will be a no-op unless the `journal` config option is set to a\ntruthy value. This will allow you to conditionally write to the journal based\non the Lapis environment.\n\n```lua\n-- config.lua\nlocal config = require(\"lapis.config\")\n\nconfig(\"production\", {\n  systemd = {\n    journal = true\n  }\n})\n```\n\n## Reading logs\n\nThis will loop forever listening for new log messages.\n\n```lua\nlocal j = require(\"lapis.systemd.journal\")\n\nfor entry in j.listen() do\n  print(\"Got entry:\")\n  for k, v in pairs(entry) do\n    print(\"\"k k,v)\n  end\nend\n```\n\n","funding_links":[],"categories":["Lua"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleafo%2Flapis-systemd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleafo%2Flapis-systemd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleafo%2Flapis-systemd/lists"}