Skip to content

Install the App

Matt Janda edited this page Nov 10, 2026 · 5 revisions

The GrayMoon App runs in Docker. It serves the web UI and orchestration API. It does not run git or touch your repository folders - that is the Worker's job.

Docker or Desktop

GrayMoon runs in one of two modes. They are independent, so pick one per machine:

  • Docker (this page): the App runs alone in a container and you use it from a browser. The Docker image is the web app only.
  • GrayMoon Desktop: a Windows app that installs and starts its own GrayMoon App next to it (on this machine, loopback only) and shows it in a native window. It does not need Docker, and it does not connect to a Docker container.

In both modes the Worker runs on your machine and does the git and filesystem work.

Run with Docker

Default port is 8384. Mount a volume if you want the SQLite database to survive container recreation:

docker run -d --restart unless-stopped --name graymoon -p 8384:8384 -v graymoon:/app/db jandini/graymoon:latest

Open http://localhost:8384 in your browser.

Opening GrayMoon from another machine

By default the container accepts browser pages only from the machine it runs on (http://localhost:8384). To use it from other machines, pass every host name or address people type in the browser in GRAYMOON_AllowedHosts, separated by ;, and keep localhost:

docker run -d --restart unless-stopped --name graymoon -p 8384:8384 -v graymoon:/app/db -e "GRAYMOON_AllowedHosts=localhost;nas.local;192.168.1.10" jandini/graymoon:latest

Without the variable, a page opened under another name loads but stays disconnected, and the container log shows a warning that names the variable. Once it is set, a name that is not in the list gets a 400 response. Behind a reverse proxy, list the public host name.

Pairing the Worker

GrayMoon refuses a Worker that is not paired. On the Worker page click Show pairing code, run the install command, and paste the code when asked (it is valid for 10 minutes and works once). A Worker installed with an older version without a code shows as offline: reinstall it the same way. See Why the Worker is paired.

Token encryption key (recommended outside local play)

Connector tokens are encrypted at rest. To set your own key, pass TokenKey as any password-like value (it is hashed into a key automatically). Advanced users can pass a Base64-encoded key instead:

docker run -d --restart unless-stopped --name graymoon -p 8384:8384 -v graymoon:/app/db -e TokenKey="my strong password here" jandini/graymoon:latest

Update a running container

docker pull jandini/graymoon:latest && docker stop graymoon && docker rm graymoon && docker run -d --restart unless-stopped --name graymoon -p 8384:8384 -v graymoon:/app/db jandini/graymoon:latest

With a token key:

docker pull jandini/graymoon:latest && docker stop graymoon || true && docker rm graymoon || true && docker run -d --restart unless-stopped --name graymoon -p 8384:8384 -v graymoon:/app/db -e TokenKey="my strong password here" jandini/graymoon:latest

After the App is up

  1. Install the Worker on the machine where your repositories live.
  2. Add connectors and confirm each is Active with status OK.
  3. Continue with the full Getting started walkthrough.

GrayMoon Desktop is a separate way to run GrayMoon, not a client for the Docker App - see Docker or Desktop. See also Layout.

Desktop shell

Window, tray, Check for updates..., and About are on the Desktop page. The Docker commands on this page stay the way to run the browser App.

Clone this wiki locally