https://github.com/obsidiansystems/obelisk-systemd
Turn your obelisk app into a systemd service
https://github.com/obsidiansystems/obelisk-systemd
Last synced: about 1 month ago
JSON representation
Turn your obelisk app into a systemd service
- Host: GitHub
- URL: https://github.com/obsidiansystems/obelisk-systemd
- Owner: obsidiansystems
- Created: 2020-12-14T21:37:19.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-05-25T15:12:13.000Z (almost 3 years ago)
- Last Synced: 2025-03-25T07:02:00.952Z (2 months ago)
- Language: Nix
- Size: 32.2 KB
- Stars: 9
- Watchers: 19
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog.md
Awesome Lists containing this project
README
# obelisk-systemd
[](https://nixos.org) [](https://github.com/obsidiansystems/obelisk)
Define systemd services for obelisk applications. Module options are documented in [module-options.md](./module-options.md).
* [User-level systemd service via home-manager](#user-level-systemd-service-via-home-manager)
* [Example configuration](#example-configuration)
* [Fetch sources](#fetch-sources)
* [Configure obelisk app](#configure-obelisk-app)
* [home-manager configuration](#home-manager-configuration)
* [Activate](#activate)
* [System-level systemd service via NixOS](#system-level-systemd-service-via-nixos)
* [Example configuration](#example-configuration-1)
* [Fetch sources](#fetch-sources-1)
* [Configure obelisk app](#configure-obelisk-app-1)
* [NixOS Configuration](#nixos-configuration)
## User-level systemd service via home-manager
The [user](user) module defines a user-level systemd service that can be imported into a [home-manager](https://github.com/nix-community/home-manager/blob/master/README.md) configuration.
### Example configuration
#### Fetch sources
To get started, clone this repo and your obelisk application into your home-manager configuration folder. We recommend using [nix-thunk](https://github.com/obsidiansystems/nix-thunk) to pack the obelisk application source, but this is optional.
```bash
cd ~/.config/nixpkgs
git clone [email protected]:obsidiansystems/obelisk-systemd
nix-thunk pack obelisk-systemd
git clone [email protected]:obsidian.systems/lithograph
nix-thunk pack lithograph
```
#### Configure obelisk app
You'll also need to create the config folder for your project. Our example project, lithograph, requires a config folder that looks like the following:
```
config
├── backend
│ └── clientSessionKey
└── common
└── route
```
Configuration is very app-specific, so consult your application's documentation to see what sort of configuration you need to provide. There's usually a development config available in the application repo, which might be useful as a starting point.
We'll use the following commands to create the config:
```bash
mkdir -p config/backend
mkdir -p config/common
dd if=/dev/urandom bs=96 count=1 of=config/backend/clientSessionKey
echo "http://localhost:8080" > config/common/route
```
#### home-manager configuration
Now in `home.nix` you can import the user systemd module and specify your app configuration. For documentation of all of the module options, see [module-options.md](./module-options.md).
```nix
{ config, lib, pkgs, ... }:
{
imports = [
(import ./obelisk-systemd { inherit config lib; }).user
];
obelisks."lithograph" = {
obelisk = (import ./lithograph {}).exe;
configSource = "/path/to/config";
port = 8080;
};
}
```
#### Activate
Running `home-manager switch` should activate this service.
You can inspect the running service using `systemctl`. For example:
```bash
systemctl status --user lithograph
```
## System-level systemd service via NixOS
The [system](system) module defines a system-level systemd service that can be imported into a [NixOS](https://nixos.org/nixos) configuration.
### Example configuration
#### Fetch sources
Clone this repository and your obelisk application into your nixos configuration folder (usually `/etc/nixos/`).
```bash
cd /etc/nixos
git clone [email protected]:obsidiansystems/obelisk-systemd
git clone [email protected]:obsidian.systems/lithograph
```
#### Configure obelisk app
Create a configuration folder for your application. For example:
```bash
mkdir -p config/backend
mkdir -p config/common
dd if=/dev/urandom bs=96 count=1 of=config/backend/clientSessionKey
echo "https://lithograph.example.com" > config/common/route
```
#### NixOS Configuration
Now in your `configuration.nix`, you can import the system systemd module and specify your app configuration. For documentation of all of the module options, see [module-options.md](./module-options.md).
```nix
{ config, lib, pkgs, ... }:
{
imports = [
(import /obelisk-systemd { inherit config lib; }).system
];
obelisks."lithograph" = {
obelisk = (import ./lithograph {}).exe;
configSource = "/path/to/config";
port = 8080;
enableNginxReverseProxy = true;
enableHttps = true;
virtualHostName = "lithograph.example.com";
acmeCertAdminEmail = "[email protected]";
};
}
```