GITDECK WEB / INSTALLATION
Your dashboard.
On your server.
Run Gitdeck on your computer or a server you manage. With Docker Compose, the app and its data find their place in a few steps.
Based on the project READMEBefore you start
You need Git, a GitHub account, and Docker with Compose. Docker Desktop includes Compose; on Linux you can use the Docker Engine plugin. With Docker, you do not need Node.js installed on your computer.
Install Docker ComposeThis guide is for the web dashboard. The iOS app connects directly to providers and works without this installation.
01 / GITHUB
Access that stays yours.
The project's Docker configuration uses a GitHub OAuth App with Device Flow. Create it once; you only need its Client ID.
- Open GitHub Developer settings ↗ and choose OAuth Apps → New OAuth App.
- Choose a name, such as Gitdeck (local). For Homepage URL and Authorization callback URL, you can use
http://127.0.0.1:8765. - Register the app, enable Enable Device Flow, and save with Update application.
- Copy the Client ID. There is no need to generate a client secret.
On first launch, Gitdeck shows a code and the GitHub authorization link. Approve access in your browser; the server stores the token and never exposes it to the frontend.
02 / DOCKER COMPOSE
Ready to go, in a container.
The repository includes a Dockerfile and docker-compose.yml. Run these commands in your terminal.
Before continuing, set up your GitHub Client ID.
1. Get the project
git clone https://github.com/debba/gitdeck.git
cd gitdeck2. Create the .env file
In the gitdeck folder, create an .env file and replace the example value with the Client ID you just copied.
GITHUB_CLIENT_ID=Iv1.xxxxxxxxxxxxxxxx3. Start the dashboard
docker compose up -d --buildOpen http://127.0.0.1:8765 on the computer running Docker and complete GitHub sign-in. The first build may take a few minutes.
Your data stay in place.
Accounts and snapshots are saved in the gitdeck-data volume, mounted at /home/node/.gitdeck. The volume keeps your data when the container is recreated. The published port is 8765.
On a remote server, configure HTTPS and restrict access to your instance.
Prefer Docker without Compose?
From the project folder, using the same .env file:
docker build -t gitdeck .
docker run -d --name gitdeck \
-p 8765:8765 \
--env-file .env \
-v gitdeck-data:/home/node/.gitdeck \
gitdeck03 / NODE.JS
Docker is optional.
You can run Gitdeck directly with Node.js and npm. Use Node.js 22.12 or later, or 20.19 or later in the 20 release line, to meet Vite's requirements. Export your Client ID in the terminal before starting.
git clone https://github.com/debba/gitdeck.git
cd gitdeck
npm install
export GITHUB_CLIENT_ID=Iv1.xxxxxxxxxxxxxxxx
npm run build
npm startThe production build serves the API and interface at http://127.0.0.1:8765. Tokens and snapshots are stored in ~/.gitdeck/.
Want to work on the code?
After npm install and exporting the Client ID, start development mode:
npm run devThe interface runs at http://127.0.0.1:5173 and forwards API requests to the backend on port 8765.
04 / CONFIGURATION
Your accounts. Your choices.
After signing in, use the account picker to add GitLab or Forgejo, including your own instances. For GitLab, use a personal token with the api scope; for Forgejo, enter your token and instance address. Features and data depend on provider permissions.
With Compose, edit .env to set variables supported by the included file, then recreate the container. With Node.js, export variables in the process environment. AI is optional.
| Variable | Use |
|---|---|
GITHUB_CLIENT_IDRequired for Device Flow | Client ID of your GitHub OAuth App. |
GITHUB_OAUTH_SCOPESOptional | GitHub permissions. Default: repo read:org project read:user user:email. |
OPENAI_API_KEYOptional | Enables AI digests in the dashboard. Other features work without it. |
OPENAI_DIGEST_MODELOptional | Model for AI digests. Default: gpt-4.1-mini. |
GH_AUTH_MODEManual setup | device (default), gh-cli, or token. The included Compose file uses Device Flow. |
HOST / PORTManual setup | Server address and port. Defaults: 127.0.0.1 and 8765. Inside the container: 0.0.0.0 and 8765. |
05 / MAINTENANCE
Stay on course.
Update from the repository
git pull --ff-only
docker compose up -d --buildCheck status and logs
docker compose ps
docker compose logs -f gitdeckStop containers, keep your data
docker compose downThe persistent volume remains available. Run docker compose up -d to start again. With Node.js, run npm install and npm run build after git pull, then restart npm start.
Explore the project on GitHub