Deployment Guide

This guide explains how to install and deploy build artifacts. Repository maintainers preparing a version, creating a tag, or monitoring an official release should see the Release Guide.

Recommended Release Flow (CI/CD)

Use the repository Package workflow (.github/workflows/package.yml) for release and deployment artifacts. Do not treat local script output as the official release source.

• Manual package: open GitHub Actions → Package → Run workflow, then choose dev or main; manual runs upload Actions artifacts only.
• Official release: push a v* tag on main; CI builds packages and publishes GitHub Release assets.
• CI artifacts: dinotty-macos contains .dmg, dinotty-linux contains desktop .deb / .AppImage and the server dinotty-server_*.deb, and dinotty-windows contains the NSIS installer and portable .exe.
• Artifact staging: CI copies packages to dist/package-artifacts/ before upload. Manual-run artifacts are retained for 14 days by default.

Local Script Scope

./scripts/build.sh and ./scripts/build-linux-deb.sh are only for temporary local builds, verification, or troubleshooting after changing code. Use the CI/CD flow above for deployment and releases.

# macOS, run from the repository root; only for temporary local builds after code changes
./scripts/build.sh native
./scripts/build.sh list

# Remote Linux deb build; only for local troubleshooting after code changes
./scripts/build-linux-deb.sh

Linux systemd Deploy (Use CI deb)

Download the server deb from the Package workflow dinotty-linux artifact or from GitHub Releases, then install it:

sudo apt install ./dinotty-server_*.deb

# Management commands
systemctl status dinotty       # Check status
systemctl restart dinotty      # Restart
systemctl stop dinotty         # Stop
journalctl -u dinotty -f       # View live logs

# Update config and restart
sudo vim /etc/dinotty/env      # Edit port, token, log level
sudo systemctl restart dinotty

Installing the deb deploys dinotty-server, the systemd unit, and /etc/dinotty/env.example, then enables and starts dinotty.service.

For temporary local binary validation after changing code, pass the local build output explicitly:

sudo bash deploy/systemd/install.sh --bin target/release/dinotty-server --token your-secret-token
sudo bash deploy/systemd/uninstall.sh

Linux Desktop Package

Download desktop packages from the CI dinotty-linux artifact or from GitHub Releases:

# deb installer
sudo apt install ./Dinotty*.deb

# Or run the AppImage directly
chmod +x ./Dinotty*.AppImage
./Dinotty*.AppImage

macOS Desktop Package

Download the .dmg from the CI dinotty-macos artifact or from GitHub Releases, then open it and follow the system installer prompts.

Windows Desktop Package

Download packages from the CI dinotty-windows artifact or from GitHub Releases:

• NSIS installer: suitable for normal install and uninstall flows.
• Portable .exe: suitable for install-free testing.

For auto-start on Windows, wrap the portable executable with Task Scheduler, NSSM, or WinSW.

Docker Deploy

Docker images are still built through the local Compose flow:

cd deploy/docker

# Configure environment variables
cp .env.example .env
# Edit .env to set DINOTTY_TOKEN, WORKSPACE_DIR, etc.

# Build and start (supports amd64 and arm64)
docker compose up -d --build

# Management commands
docker compose logs -f         # View logs
docker compose restart         # Restart
docker compose down            # Stop and remove

# Multi-arch build and push
docker buildx build --platform linux/amd64,linux/arm64 \
  -t your-registry/dinotty:latest --push \
  -f deploy/docker/Dockerfile .

On Windows, use Docker Desktop with Linux containers. Set workspace paths in .env using paths visible inside Docker Desktop mounts.

Cross-Platform Packages

Cross-platform desktop packages are generated by the Package workflow matrix:

Platform	CI runner	Artifacts
macOS	macos-latest	.dmg
Linux	ubuntu-22.04	desktop .deb / .AppImage, server dinotty-server_*.deb
Windows	windows-latest	NSIS .exe, portable .exe

Configuration

Parameter	Method	Default	Description
Port	--port / -p	8999	Server listen port
Token	DINOTTY_TOKEN env var or config file	Unconfigured / first-time setup	Access auth token; when empty, Dinotty starts the first-time setup flow
Log level	RUST_LOG env var	info	trace / debug / info / warn / error
Shell	Unix: SHELL; Windows: DINOTTY_SHELL	Auto-detect	Windows tries DINOTTY_SHELL, then pwsh.exe, powershell.exe, %ComSpec% / cmd.exe

Config And Data Directories

Platform	Config directory	Plugin directory
Linux	~/.config/dinotty	~/.dinotty/plugins
macOS	~/Library/Application Support/dinotty	~/.dinotty/plugins
Windows	%APPDATA%\dinotty	%USERPROFILE%\.dinotty\plugins

Tokens, settings.json, audit logs, and webhook secrets are stored in the config directory. Plugin persistent data lives under .dinotty/plugin-data in the user's home directory.