Quick Start

Create your first systemd service with mkunit.

This guide will walk you through creating, installing, and managing your first systemd service using mkunit.

Step 1: Create a Simple Service

Let's create a user service for a simple web server. First, make sure you have something to run:

# Create a simple test script
mkdir -p ~/myapp
cat > ~/myapp/server.sh << 'EOF'
#!/bin/bash
echo "Server starting on port 8080..."
while true; do
  echo "HTTP/1.1 200 OK\n\nHello from mkunit!" | nc -l -p 8080 -q 1
done
EOF
chmod +x ~/myapp/server.sh

Now create the service:

mkunit service myapp --exec "$HOME/myapp/server.sh" --install

This creates a unit file and installs it to ~/.config/systemd/user/myapp.service.

Step 2: Start the Service

# Start the service
systemctl --user start myapp

# Check status
mkunit status myapp

You should see the service is active and running.

Step 3: View Logs

# View recent logs
mkunit logs myapp

# Follow logs in real-time
mkunit logs myapp -f

Step 4: Enable on Boot

To start the service automatically when you log in:

systemctl --user enable myapp

Or do it all in one command:

mkunit service myapp --exec "$HOME/myapp/server.sh" --install --enable --start

Step 5: Stop and Clean Up

# Stop the service
systemctl --user stop myapp

# Remove the service completely
mkunit remove myapp

Real-World Example: Node.js Application

Here's a more realistic example for a Node.js application:

mkunit service my-api \
  --exec "node server.js" \
  --workdir /home/user/my-api \
  --env "NODE_ENV=production" \
  --env "PORT=3000" \
  --restart on-failure \
  --install --enable --start

Real-World Example: Python Application

mkunit service my-flask-app \
  --exec "/home/user/myapp/venv/bin/python app.py" \
  --workdir /home/user/myapp \
  --env-file /home/user/myapp/.env \
  --restart always \
  --install --start

Creating a Scheduled Task (Timer)

Run a backup script daily:

# First, create the service for the task
mkunit service backup \
  --exec "/home/user/scripts/backup.sh" \
  --type oneshot \
  --install

# Then create a timer to run it daily
mkunit timer backup \
  --on-calendar daily \
  --persistent \
  --install --enable --start

Preview Before Installing

Use --dry-run to see what would be created:

mkunit service myapp --exec "./server" --restart always --dry-run

This prints the unit file without writing anything.

User vs System Services

User Services (default)

• Run as your user
• Start when you log in
• No sudo required
• Stored in ~/.config/systemd/user/

System Services

• Run as any user (often root or a service account)
• Start at boot
• Requires sudo
• Stored in /etc/systemd/system/

# Create a system service
sudo mkunit service nginx-custom \
  --exec "/usr/bin/nginx" \
  --system \
  --user nginx \
  --install --enable

Version Control Workflow

Keep your unit files in git and symlink them to systemd:

# Create unit file in your repo (not installed to systemd)
mkunit service myapp \
  --exec "/usr/bin/myapp" \
  --output ./systemd/myapp.service \
  --no-interactive

# Commit to git
git add systemd/myapp.service
git commit -m "Add myapp service"

# Link to systemd (creates symlink, enables unit)
mkunit link ./systemd/myapp.service --install

See mkunit link for more details.