---
name: ship-service
description: Manage systemd services for deployed apps. Start, stop, restart, view status and logs. Use when you need to control a running service or diagnose problems.
argument-hint: "<app-name> [start|stop|restart|status|logs] [host-nickname]"
---

# ship-service

Manage systemd services for apps deployed on a ship VPS.

## Read Config

```bash
python3 -c "
import json, os
cfg = json.load(open(os.path.expanduser('~/.config/ship/config.json')))
nick = '<nickname-or-default>'
h = cfg['hosts'].get(nick, cfg['hosts'][cfg['default']])
print(h['host'])
"
```

## Usage Patterns

### Status

```bash
ssh <host> "sudo systemctl status <app-name> --no-pager"
```

Shows whether the service is running, its PID, memory usage, and recent log lines.

### Restart

```bash
ssh <host> "sudo systemctl restart <app-name>"
```

Use after changing env vars or replacing the binary.

### Stop

```bash
ssh <host> "sudo systemctl stop <app-name>"
```

### Start

```bash
ssh <host> "sudo systemctl start <app-name>"
```

### View logs

Recent logs (last 50 lines):
```bash
ssh <host> "sudo journalctl -u <app-name> -n 50 --no-pager"
```

Follow live logs:
```bash
ssh <host> "sudo journalctl -u <app-name> -f"
```

Logs since last boot:
```bash
ssh <host> "sudo journalctl -u <app-name> -b --no-pager"
```

### Enable (start on boot)

```bash
ssh <host> "sudo systemctl enable <app-name>"
```

### Disable (don't start on boot)

```bash
ssh <host> "sudo systemctl disable <app-name>"
```

### View the systemd unit file

```bash
ssh <host> "sudo cat /etc/systemd/system/<app-name>.service"
```

### Remove a service entirely

Only do this if the user explicitly asks to remove/uninstall an app:

```bash
ssh <host> "sudo systemctl stop <app-name> && sudo systemctl disable <app-name> && sudo rm /etc/systemd/system/<app-name>.service && sudo systemctl daemon-reload"
```

Confirm with the user before removing. Note that this does not delete the binary,
data directory, env file, or Caddy config — those are managed separately.

## Diagnosing Problems

If a service is failing, check:

1. Service status for the error:
```bash
ssh <host> "sudo systemctl status <app-name> --no-pager"
```

2. Full logs for context:
```bash
ssh <host> "sudo journalctl -u <app-name> -n 100 --no-pager"
```

3. Whether the binary exists and is executable:
```bash
ssh <host> "ls -la /usr/local/bin/<app-name>"
```

4. Whether the env file exists and looks correct:
```bash
ssh <host> "sudo cat /etc/ship/env/<app-name>.env"
```

5. Whether the port is already in use by something else:
```bash
ssh <host> "sudo ss -tlnp | grep <port>"
```

## Notes

- If the user just says "restart foodtracker" or "check the logs for myapp", infer the action
- After a restart, give it a moment then check status to confirm it came up
- If a service repeatedly crashes, look at the logs before suggesting a fix
- Use default host unless another is specified