mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-11-16 03:09:33 +01:00
Name the real trigger and CODEMAN_NO_ADMIN=0 in the READMEs and the Installation page, add the install without git to the update tables and the updater notes, record the installer's downloads in the supply chain section, and say that the data directory question also removes a kept runtime. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
220 lines
8.1 KiB
Markdown
220 lines
8.1 KiB
Markdown
# Running As A Service
|
|
|
|
Keeping Codeman up: past the shell you started it in, past a logout, past a reboot. Plus
|
|
logs, updates, and running more than one instance.
|
|
|
|
## Three levels
|
|
|
|
| Level | Survives | Command |
|
|
| -------------------- | ----------------------------------------- | ------------------------- |
|
|
| Foreground | Nothing. Dies with the terminal. | `codeman web` |
|
|
| Detached | Closing the shell and logging out. | `codeman web -d` |
|
|
| Service | Reboots. | `codeman service install` |
|
|
|
|
Agents themselves survive all three, because they live in tmux. Stopping the server never
|
|
stops the agents.
|
|
|
|
## Detached mode
|
|
|
|
```bash
|
|
codeman web -d # start detached; logs to ~/.codeman/web.log
|
|
codeman web --status # is it up, and on which pid
|
|
codeman web --stop # graceful stop; agents keep running
|
|
```
|
|
|
|
`-d` waits until the server actually answers before reporting success, so a port clash never
|
|
reads as a successful start.
|
|
|
|
Two implementation details that explain the behaviour:
|
|
|
|
- It relaunches the same entry script detached, so there is no controlling terminal and no
|
|
shell job entry. `nohup` is **not** what makes this work: Node re-arms the hangup signal to
|
|
its default even when it inherits "ignore", and Codeman handles that signal with a graceful
|
|
shutdown, so a delivered hangup would still stop the server.
|
|
- `--stop` verifies the process still looks like a Codeman server before signalling it,
|
|
because process ids get recycled.
|
|
|
|
**It refuses to start a second server on the same data directory.** Two servers sharing a
|
|
tmux socket attach to each other's live sessions.
|
|
|
|
## Installing as a service
|
|
|
|
```bash
|
|
codeman service install # systemd user unit on Linux, LaunchAgent on macOS
|
|
codeman service status
|
|
codeman service uninstall
|
|
```
|
|
|
|
The installer's final menu offers this too.
|
|
|
|
Notable behaviours:
|
|
|
|
- **Your PATH is baked into the unit.** launchd hands a job
|
|
`/usr/bin:/bin:/usr/sbin:/sbin`, which finds neither a Homebrew or nvm `node` nor `tmux`
|
|
or `claude`. This is the single most common cause of a hand-written unit that starts and
|
|
immediately dies.
|
|
- **`CODEMAN_PASSWORD` is never written into the unit file.** Add it yourself if the service
|
|
needs authentication.
|
|
- **It refuses when a server is already running** on that data directory, for the same reason
|
|
detached mode does.
|
|
- **It verifies rather than assumes.** `launchctl load` and a clean spawn are both silent
|
|
about a server that starts and immediately exits, so the parent polls until the child
|
|
answers or dies.
|
|
|
|
On Linux, if you want the service running while you are not logged in:
|
|
|
|
```bash
|
|
loginctl enable-linger $USER
|
|
```
|
|
|
|
On macOS, a LaunchAgent starts when you log in, not at boot. A headless Mac (no GUI login)
|
|
needs a system LaunchDaemon instead, written by hand as root. The installer recognises an
|
|
existing `/Library/LaunchDaemons/com.codeman.web.plist` and leaves it alone rather than
|
|
installing a LaunchAgent next to it, since the two would fight over the port; remove the
|
|
daemon first if you want to switch. The same login caveat applies to the App Store and
|
|
standalone Tailscale apps, so on a headless Mac the Tailscale URL only comes back after a
|
|
reboot if the open-source `tailscaled` is used.
|
|
|
|
### Writing the unit by hand
|
|
|
|
**Linux (systemd user unit):**
|
|
|
|
```bash
|
|
mkdir -p ~/.config/systemd/user
|
|
cat > ~/.config/systemd/user/codeman-web.service << EOF
|
|
[Unit]
|
|
Description=Codeman Web Server
|
|
After=network.target
|
|
|
|
[Service]
|
|
Type=simple
|
|
ExecStart=$(which node) $HOME/.codeman/app/dist/index.js web
|
|
Restart=always
|
|
RestartSec=10
|
|
|
|
[Install]
|
|
WantedBy=default.target
|
|
EOF
|
|
systemctl --user daemon-reload
|
|
systemctl --user enable --now codeman-web
|
|
loginctl enable-linger $USER
|
|
```
|
|
|
|
**macOS (LaunchAgent):**
|
|
|
|
```bash
|
|
mkdir -p ~/Library/LaunchAgents
|
|
cat > ~/Library/LaunchAgents/com.codeman.web.plist << EOF
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
|
|
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
<plist version="1.0">
|
|
<dict>
|
|
<key>Label</key>
|
|
<string>com.codeman.web</string>
|
|
<key>ProgramArguments</key>
|
|
<array>
|
|
<string>$(which node)</string>
|
|
<string>$HOME/.codeman/app/dist/index.js</string>
|
|
<string>web</string>
|
|
</array>
|
|
<key>RunAtLoad</key><true/>
|
|
<key>KeepAlive</key><true/>
|
|
<key>StandardOutPath</key>
|
|
<string>/tmp/codeman.log</string>
|
|
<key>StandardErrorPath</key>
|
|
<string>/tmp/codeman.log</string>
|
|
</dict>
|
|
</plist>
|
|
EOF
|
|
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist
|
|
```
|
|
|
|
Prefer `codeman service install` where you can. It handles the PATH problem for you.
|
|
|
|
## Logs
|
|
|
|
```bash
|
|
journalctl --user -u codeman-web -f # systemd
|
|
tail -f ~/.codeman/web.log # detached mode
|
|
log stream --predicate 'process == "node"' # macOS, noisy
|
|
```
|
|
|
|
## Updating
|
|
|
|
| Install route | Update with |
|
|
| ------------- | ------------------------------------------------------------------------ |
|
|
| Installer | Re-run the one-liner, or **App Settings → System → Updates**. |
|
|
| Installer, without git | Re-run the one-liner. The in-app updater says so instead of offering an update. |
|
|
| npm | `npm update -g aicodeman` |
|
|
| git clone | `git pull && npm install && npm run build`, then restart. |
|
|
| Docker Compose | Re-run `Start-Codeman.sh`, or the in-app updater, which restarts the container in place. |
|
|
|
|
### The in-app updater
|
|
|
|
**App Settings → System → Updates**, for git-clone installs supervised by systemd or
|
|
launchd. npm installs and installs without git report as non-updatable, and an unsupervised
|
|
install is told to restart manually.
|
|
|
|
The interesting part is that the update restarts the very process running it. So the real
|
|
work runs in a **detached script that outlives the restart** and writes progress to a status
|
|
file, which the browser polls across the connection drop. A dirty tree is stashed rather
|
|
than discarded.
|
|
|
|
### After updating
|
|
|
|
Sessions are unaffected: they live in tmux and the server reattaches. If the UI looks stale,
|
|
reload; on iOS Safari, close the tab completely and reopen.
|
|
|
|
## Running two instances
|
|
|
|
The data directory and the tmux socket are process wide, so a second server on the defaults
|
|
will discover and attach the first one's sessions. Scope both together:
|
|
|
|
```bash
|
|
CODEMAN_INSTANCE=beta CODEMAN_PORT=5000 codeman web
|
|
```
|
|
|
|
Service unit names are instance-scoped too, so a beta instance can be installed as its own
|
|
service without colliding with the main one. `CODEMAN_DATA_DIR` and `CODEMAN_TMUX_SOCKET`
|
|
exist for the rare case where they need to differ, but setting only one of them recreates
|
|
exactly the problem you were avoiding.
|
|
|
|
## Running Codeman itself in Docker
|
|
|
|
The Compose deployment in `docker/` runs the server in a container and spawns Docker cases
|
|
as sibling containers through the mounted host socket. Start it with
|
|
`bash docker/Start-Codeman.sh` rather than a bare `docker compose up`: the script pre-creates
|
|
the bind-mounted directories with the right owner, honours a `docker-compose.override.yml`,
|
|
and refreshes the build volumes when the checkout moved under them. The in-app updater
|
|
applies code only and restarts by letting the container exit, so it refuses a release that
|
|
changes the Dockerfile, the compose file, or adds a new `.env` key, until you re-run the
|
|
script. Guide:
|
|
[`docker/README.md`](https://github.com/Ark0N/Codeman/blob/master/docker/README.md).
|
|
|
|
## The tunnel as a service
|
|
|
|
```bash
|
|
systemctl --user enable codeman-tunnel
|
|
loginctl enable-linger $USER
|
|
```
|
|
|
|
Or the toggle in **App Settings → System → Remote access**. See
|
|
[Remote Access](Remote-Access).
|
|
|
|
## Health checks
|
|
|
|
```bash
|
|
curl -s localhost:3000/api/status | jq '.version, .uptime'
|
|
codeman web --status
|
|
codeman doctor
|
|
```
|
|
|
|
Add `-k` and the `https://` URL on an HTTPS install.
|
|
|
|
## Read next
|
|
|
|
- [Installation](Installation) - the routes and what each supports.
|
|
- [Remote Access](Remote-Access) - exposing it once it stays up.
|
|
- [Troubleshooting](Troubleshooting) - when it does not.
|