initial commit of role

README.md

@@ -0,0 +1,78 @@
+<!--
+SPDX-FileCopyrightText: 2023 Max Mehl <https://mehl.mx>
+SPDX-FileCopyrightText: 2025 Max Mehl <https://mehl.mx>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Ansible role for creating users systemd services
+
+[![REUSE status](https://api.reuse.software/badge/src.mehl.mx/mxmehl/ansible-role-systemd-user)](https://api.reuse.software/info/src.mehl.mx/mxmehl/ansible-role-systemd-user)
+
+This Ansible role allows for easy and painless creation of systemd services for a user running only with this user's privileges.
+
+## Requirements
+
+* Debian and `apt`
+* `python3`
+
+## Installation
+
+Add this role as a submodule: `git submodule add https://src.mehl.mx/mxmehl/ansible-role-systemd-user.git roles/systemd-user`
+
+## Usage and examples
+
+### Basic
+
+The example below will add, enable and start `my-daemon.service` for the user `user1`. It expects the existence of a template file `my-daemon.service.j2` reachable for this role.
+
+```yaml
+- name: Setup systemd user service
+  include_role:
+    name: systemd-user  # name of the role on your system
+  vars:
+    # Name of the user you want to create the service for
+    user: "user1"
+    # Name of the service
+    service: my-daemon
+```
+
+### Custom template / file
+
+The following example does the same as before, but allows you to use an own template. The effective service file will still be `my-daemon.service`.
+
+Alternatively, you can just copy the service file using the `copy_file` variable.
+
+```yaml
+- name: Setup systemd user service
+  include_role:
+    name: systemd-user  # name of the role on your system
+  vars:
+    user: "user1"
+    service: my-daemon
+    # Use customservice.j2 as template
+    template: customservice.j2
+    # Use my-service.service as local file that shall be used as service file
+    # copy_file: my-service.service
+```
+
+### Define state of service
+
+By default, the role reloads the user's systemd daemon and starts and enables the new service. You can configure that:
+
+```yaml
+- name: Setup systemd user service
+  include_role:
+    name: systemd-user  # name of the role on your system
+  vars:
+    user: "user1"
+    service: my-daemon
+    # Service shall be stopped, disabled, and the systemd daemon not reloaded
+    systemd_state: stopped
+    systemd_enabled: false
+    systemd_daemon_reload: false
+```
+
+## License
+
+Apache-2.0, Copyright Max Mehl