stacks-puppet-node/docs/init.md

Sample init scripts and service configuration for stacks-blockchain

Sample scripts and configuration files for systemd and SysVinit can be found in the contrib/init folder.

contrib/init/stacks.service:    systemd service unit configuration
contrib/init/stacks.init:       SysV style init script

Service User

All Linux startup configurations assume the existence of a "stacks" user and group. They must be created before attempting to use these scripts. The MacOS configuration assumes stacks-blockchain will be set up for the current user.

Configuration

For an example configuration file that describes the configuration settings, see mainnet-follower-conf.toml. Available configuration options are documented here: https://docs.stacks.co/references/stacks-node-configuration

Paths

Linux

All three configurations assume several paths that might need to be adjusted.

Binary:              /usr/local/bin/stacks-node
Configuration file:  /etc/stacks-blockchain/Config.toml
Data directory:      /stacks-blockchain
PID file:            /run/stacks-blockchain/stacks.pid
Lock file:           /var/lock/subsys/stacks (SysVinit)

The PID directory and data directory should both be owned by the stacks user and group. It is advised for security reasons to make the configuration file and data directory only readable by the stacks user and group.

NOTE: When using the systemd .service file, the creation of the aforementioned directories and the setting of their permissions is automatically handled by systemd. Directories are given a permission of 710, giving the stacks group access to files under it if the files themselves give permission to the stacks group to do so. This does not allow for the listing of files under the directory.

$ mkdir -p /etc/stacks-blockchain/
$ mkdir -p /stacks-blockchain
$ useradd stacks
$ chown -R stacks:stacks /stacks-blockchain/
$ chgrp -R stacks /etc/stacks-blockchain

macOS

Binary:              /usr/local/bin/stacks-node
Configuration file:  /etc/stacks-blockchain/Config.toml

The Config.toml file is presumed to have group ownership by the wheel group, with the current user having membership to that group. The data directory defined in the config is required to be writable by the current user. Logs (stdout & stderr) are saved under /tmp/stacks-blockchain.log

Installing Service Configuration

systemd

Installing this .service file consists of just copying it to /usr/lib/systemd/system directory, followed by the command systemctl daemon-reload in order to update running systemd configuration.

To test, run systemctl start stacks and to enable for system startup run systemctl enable stacks

NOTE: When installing for systemd in Debian/Ubuntu the .service file needs to be copied to the /lib/systemd/system directory instead.

SysVinit

Copy stacks.init to /etc/init.d/stacks. Test by running service stacks start.

Using this script, you can adjust the config path and log location to the stacks-node program by setting the STACKS_BLOCKCHAIN_CONFIG and STACKS_BLOCKCHAIN_LOG environment variables in the file /etc/sysconfig/stacks-blockchain.

MacOS

Copy org.stacks.stacks-blockchain.plist into ~/Library/LaunchAgents. Load the launch agent by running launchctl load ~/Library/LaunchAgents/org.stacks.stacks-blockchain.plist.

This Launch Agent will not start the stacks-blockchain whenever the user logs in.

To start the service, you'll need to manually run the start command: launchctl start org.stacks.stacks-blockchain

NOTE: This approach is intended for those wanting to run stacks-blockchain as the current user. You will need to modify org.stacks.stacks-blockchain.plist if you intend to use it as a Launch Daemon with a dedicated stacks user.

Auto-respawn

Auto respawning is currently disabled.