Getting Started with GitOps in Five Minutes

This guide starts GitOps locally with Docker, connects GitDB to a private GitHub repository, and walks through the first administrator and organization setup.

What you need

• Docker Engine 20.10 or later.
• Node.js is not required to run the GitOps server.
• A GitHub account and a private repository for GitDB.
• A GitHub token with repository read and write permission. GitOps pushes changes back to GitDB.

Create the GitHub repository

Create an empty private repository on GitHub, for example my-gitops-db. Then create a fine-grained personal access token:

1. Open GitHub Settings, Developer settings, and Personal access tokens.
2. Create a fine-grained token and select only the GitDB repository.
3. Grant Contents: Read and write permission.
4. Copy the token. GitHub only shows it once.

Keep the token out of Git and pass it to Docker through .env.

Start GitOps with Docker

Create a directory for the local configuration and add a .env file:

mkdir gitops-local
cd gitops-local
touch .env

Add the GitDB settings below, replacing the placeholders:

GITDB_REPOSITORY_URL=https://github.com/YOUR_GITHUB_USER/my-gitops-db.git
GITDB_BRANCH=main
GITDB_ENCRYPTION_KEY=replace-with-a-long-random-secret
GITDB_DATA_PATH=./data/gitdb
GITDB_USERNAME=x-access-token
GITDB_TOKEN=replace-with-your-github-token

Start the container with the published image:

docker run -d 
  --name gitops 
  --restart unless-stopped 
  --env-file .env 
  -p 3000:3000 
  ghcr.io/getgitops/gitops:latest

Check that the server is ready:

curl http://localhost:3000/health
docker logs -f gitops

Complete the bootstrap

Open http://localhost:3000/bootstrap. The wizard has two required steps:

1. Create the cluster administrator. Enter a username, optional email, password, and password confirmation. The password must contain at least 8 characters.
2. Create the organization. Enter the organization name. The slug and description are optional.

GitOps creates the default organization roles after the second step and redirects you to the login page.

Sign in and continue

Sign in with the administrator account, then create projects and configure their access. Keep the .env file private and back up the GitHub repository together with GITDB_ENCRYPTION_KEY so the installation can be restored.