Shipherd

Run, monitor, and manage code projects on your own server. Shipherd provides a web UI, Git integrations, real-time metrics and logs, and zero-config tooling for managing your projects.

User Guide

What Shipherd Does

• Manage multiple projects (Node, Python, Go, Rust, etc.) from a single dashboard.
• Start/stop/restart projects and stream logs.
• Track health, CPU, and memory metrics in real time.
• Sync projects from GitHub, GitLab, Codeberg, and more.
• Send notifications via Email, Discord, or Webhooks on project events.
• Expose project ports securely via reverse proxy, or direct acccess on the local network.

Quickstart

Docker Run

docker run -d \
  --name shipherd \
  -p 9744:9744 \
  -v ./shipherd/data:/app/data \
  -v ./shipherd/secrets:/app/secrets \
  -v ./projects:/app/projects \
  code.marvil.co/shipherd/shipherd:latest

Docker Compose

services:
  shipherd:
    image: code.marvil.co/shipherd/shipherd:latest
    container_name: shipherd
    restart: always # Or your preferred restart policy
    environment:
      - TZ=America/New_York
      - EXPOSED_PORTS=3000,3001,3002 # For web-based projects
      - SHIPHERD_URL=http://localhost:9744
    ports:
      - "9744:9744"
      - "3000-3002:3000-3002" # Expose your project ports here
    volumes:
      - ./shipherd/data:/app/data
      - ./shipherd/secrets:/app/secrets
      - ./projects:/app/projects
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9744/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

docker compose up -d

Concepts

• Projects: A project is a codebase that you want to run and manage. It can be a Node.js app, a Python script, a Go binary, etc. You can have multiple projects in Shipherd, each with its own settings, configurations, and environment variables.
• Ports: If your project exposes a web interface or API, you can access it through your server's IP address if you have the port exposed. Otherwise, you can use Shipherd's reverse proxy feature to access it.
• Health Checks: Shipherd will regularly monitor your projects' health, CPU, and memory usage. You can set up notifications to alert you if a project goes down.
• Git Integrations: You can link your projects to Git repositories. Shipherd can pull the latest code from your repo to apply your changes.

Developer Guide

If you are looking at the source code, it is recommended that you install the Better Comments extension for your code editor to see the //! and //? comments, which indicate important notes about the code.

If you want to contribute to Shipherd or run it locally for development, you may find the DEV_MODE environment variable useful. Enabling it will enable the bypassauth token for local API testing. E2E_TEST_MODE will also enable test-only reset endpoints.

Local Development

Install dependencies:

git clone https://code.marvil.co/shipherd/shipherd.git
cd shipherd/src/backend && npm ci
cd ../frontend && npm ci
cd ../e2e && npm ci

Build and run the docker container:

docker compose up -d --build

Source

The code is published to code.marvil.co under the AGPLv3 license. You can also find it mirrored on Codeberg at codeberg.org. Contributions are welcome!