Getting started with gitrust: compile, configure, and push your first commit¶

Source : ce tutoriel intègre le contenu de gitrust/docs/GETTING_STARTED.md avec la structure pédagogique complète (objectifs Bloom, modèle mental, checkpoints observables, section « Et si ça ne marche pas »).

Goals¶

At the end of this tutorial, you will know:

• O1. Compile gitrust from source and launch the development instance locally
• O2. Configure the development environment (database, environment variables, CSS assets)
• O3. Execute a first SSH push to your local instance and check the result in the web interface

Prerequisites¶

• Technical: Rust stable ≥ 1.80 (rustc --version), PostgreSQL ≥ 15 (psql --version), Node.js ≥ 18 (node --version), Git 2.x (git --version), Docker (optional, recommended for the database)
• Pédagogique : être un utilisateur autonome de gitrust (parcours user complété ou équivalent) ; familiarité avec Rust (au moins 3 mois de pratique) et avec HTTP/PostgreSQL
• Estimated time: ~45 minutes

Overview¶

Before executing the first command, let's take 3 minutes to understand what you are going to assemble and how the parts fit together.

gitrust is a 6-crate Rust monorepo that compiles to a single binary. When you run cargo run, this binary starts two servers simultaneously: an HTTP server (:4000) for the web interface and REST API, and an SSH server (:2222) for git push/pull operations. They share the same PostgreSQL database and bare-disk repository storage.

graph TB
    subgraph sources ["Sources gitrust (monorepo Rust)"]
        C1[rustwarden-core
auth, sessions, middleware]
        C2[gitrust-core
modèles, services métier]
        C3[gitrust-git
opérations Git bare]
        C4[gitrust-web
handlers HTTP + templates]
        C5[gitrust-ssh
serveur SSH Git]
        C6[gitrust-hooks
post-receive, pre-receive]
    end

    subgraph runtime ["Processus unique (cargo run)"]
        HTTP["HTTP :4000
UI + API REST"]
        SSH["SSH :2222
git push/pull"]
    end

    subgraph storage ["Stockage"]
        PG[(PostgreSQL
comptes, dépôts,
issues, PRs)]
        REPOS[Dépôts bare
data/repos/]
    end

    C1 & C2 & C3 & C4 & C5 & C6 -->|cargo build| HTTP
    C1 & C2 & C3 & C4 & C5 & C6 -->|cargo build| SSH
    HTTP & SSH --> PG
    HTTP & SSH --> REPOS

What you will do: clone the sources → prepare PostgreSQL → copy and fill .env → compile the CSS assets → run cargo run → check the instance → push a first commit via SSH.

Step 1: Check system requirements¶

Before cloning anything, make sure you have all the necessary tools installed:

rustc --version && cargo --version && psql --version && node --version && git --version

Expected output (exact versions may vary):

rustc 1.82.0 (f6e511eec 2024-10-15)
cargo 1.82.0 (8f40fc59f 2024-10-15)
psql (PostgreSQL) 16.3
v20.11.0
git version 2.43.0

If any system dependencies are missing, install them:

# Debian / Ubuntu
sudo apt install build-essential pkg-config libssl-dev libpq-dev cmake git

# macOS
brew install postgresql openssl cmake

Checkpoint: All check commands must return an error-free version number. If rustc is not found, install Rust via curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh then reload your shell.

Step 2: Clone the project¶

git clone https://demo.gitrust.eu/gitrust/gitrust.git
cd gitrust

Expected output:

Cloning into 'gitrust'...
remote: Enumerating objects: 12847, done.
remote: Counting objects: 100% (12847/12847), done.
Receiving objects: 100% (12847/12847), 18.42 MiB | 4.20 MiB/s, done.

Checkpoint: check that the crate structure is present:

ls crates/

Expected output:

gitrust-core  gitrust-git  gitrust-hooks  gitrust-ssh  gitrust-web  rustwarden-core

Step 3: Configure the environment (.env)¶

Copy the example file and edit the 5 essential values:

cp .env.example .env

Open .env in your editor and fill in these values:

# Connexion à la base de données
DATABASE_URL=postgres://gitrust:motdepasse@localhost:5432/gitrust

# Clé secrète JWT (générez-la avec : openssl rand -hex 32)
JWT_SECRET=votre_cle_secrete_64_caracteres

# Compte administrateur créé au premier lancement
ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=MotDePasseFort123!

Les autres variables ont des valeurs par défaut raisonnables pour le développement. Consultez .env.example pour la liste complète.

Generate a real value for JWT_SECRET:

openssl rand -hex 32

Expected output (different value each run):

4a7f2c9e1b8d3f6a0e5c2b9d7f4a1e8c3b6d9f2a5e8c1b4d7f0a3e6c9b2d5f8a

Copy this value to .env for JWT_SECRET.

Checkpoint: check that no example values ​​remain in .env:

grep -E "votre_cle|example\.com|MotDePasse" .env

The command should return empty (no lines). If it returns rows, those placeholder values ​​are still present — the application will start but with an insecure configuration.

Step 4: Prepare the PostgreSQL database¶

You have two options:

Option A — Docker (recommended for beginners):

cd database && docker compose up -d && cd ..

Expected output:

[+] Running 2/2
 ✔ Container gitrust_postgres_dev  Started    0.8s
 ✔ Container gitrust_pgadmin       Started    1.1s

Option B — PostgreSQL existing on the machine:

psql -U postgres << 'SQL'
CREATE USER gitrust WITH PASSWORD 'motdepasse';
CREATE DATABASE gitrust OWNER gitrust;
SQL

Expected output:

CREATE ROLE
CREATE DATABASE

Adapt the password in DATABASE_URL in .env if you use option B.

Checkpoint: check that the base is accessible from the application:

psql "$DATABASE_URL" -c "SELECT version();"

Expected output:

                                                version
-------------------------------------------------------------------------------------------------------
 PostgreSQL 16.3 on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 13.2.0-23ubuntu4) 13.2.0, 64-bit
(1 row)

If you get psql: error: connection to server failed, check that PostgreSQL is running and that DATABASE_URL matches.

Step 5: Compile the CSS assets¶

gitrust uses Tailwind CSS + DaisyUI. Assets must be compiled locally — no CDN, all files are served from static/:

npm install
npx tailwindcss -i static/css/input.css -o static/css/style.css --minify

Expected output:

added 98 packages in 3s

Rebuilding...
Done in 1842ms.

Checkpoint: verify that the CSS file is generated:

ls -lh static/css/style.css

Expected output:

-rw-r--r-- 1 vous vous 45K avr 17 10:15 static/css/style.css

If the file is 0 bytes or does not exist, the compilation failed — run npm install again then the npx tailwindcss command.

Step 6: Launch the app¶

cargo run

The first compilation takes 2-5 minutes (all dependencies are compiled). Subsequent compilations are incremental and much faster.

Au premier lancement, gitrust exécute automatiquement : 1. Database migrations (creation of all tables) 2. Creating the administrator account (from .env) 3. Generating the SSH host key (data/ssh_host_ed25519_key) 4. Creating the repository storage directory (data/repos/)

Expected output (after compilation):

   Compiling gitrust-web v0.9.0 (/home/vous/gitrust/crates/gitrust-web)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 187.42s
     Running `target/debug/gitrust`
2026-04-17T10:20:00Z INFO  gitrust > Starting gitrust v0.9.0
2026-04-17T10:20:00Z INFO  gitrust > Running database migrations... applied 42
2026-04-17T10:20:01Z INFO  gitrust > Admin account created: admin
2026-04-17T10:20:01Z INFO  gitrust > SSH host key: SHA256:xxxxxxxxxxxxxxxxxxxx
Server listening on http://0.0.0.0:4000

Checkpoint: open http://localhost:4000 in your browser. You need to see the gitrust home page. Log in with the ADMIN_USERNAME / ADMIN_PASSWORD credentials defined in .env. If the page does not load, check that the message Server listening on http://0.0.0.0:4000 appears in the logs.

Step 7: Create a repository and push your first commit¶

In the web interface (http://localhost:4000), click on “New repository”, give a name (eg. my-project) and click Create.

Add your public SSH key in Settings > SSH Keys by pasting the contents of ~/.ssh/id_ed25519.pub.

Then in your terminal:

git clone ssh://git@localhost:2222/admin/mon-projet.git
cd mon-projet

echo "# Mon projet" > README.md
git add README.md
git commit -m "Initial commit"
git push origin main

Expected output:

Cloning into 'mon-projet'...
warning: You appear to have cloned an empty repository.
[main (root-commit) a1b2c3d] Initial commit
 1 file changed, 1 insertion(+)
 create mode 100644 README.md
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), 226 bytes | 226.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
To ssh://localhost:2222/admin/mon-projet.git
 * [new branch]      main -> main

Checkpoint: return to the browser to http://localhost:4000/admin/my-project. The page should display the README.md file with the content #My project and indicate 1 commit on the main branch.

Additional features available¶

Integrated IC (optional)¶

The CI runs on a build server via SSH + rsync. Configure in .env:

# Même machine (défaut pour le développement)
CI_REMOTE_HOST=localhost

# Ou serveur dédié
CI_REMOTE_HOST=192.168.13.110
CI_REMOTE_USER=ci-runner

Easy Mode — add .gitrust-ci.yml to the root of your repository:

language: rust

build:
  command: "cargo build --release"

tests:
  command: "cargo test"

Power Mode — place a Dagger module in .dagger/ at the root. gitrust will run dagger call -m .dagger/ ci.

Notifications¶

Configure SMTP in .env for email notifications:

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=user
SMTP_PASSWORD=password
SMTP_FROM=noreply@gitrust.eu

Interface language¶

gitrust is available in 6 languages ​​(fr, en, de, es, pt, it). Set the default language for the instance:

DEFAULT_LOCALE=fr

Summary¶

• ✓ O1 accomplished: gitrust is compiled from source and runs locally — cargo run displays “Server listening on http://0.0.0.0:4000”
• ✓ O2 accomplished: the environment is configured — .env populated, PostgreSQL connected, CSS assets generated, migrations applied
• ✓ O3 accomplished: a first SSH push was successful — the commit is visible in the web interface at http://localhost:4000/admin/mon-project

And if it doesn't work¶

Next step¶

→ 02 — First contribution: clone, build, test, PR: learn how to create a feature branch, write tests, and submit your first pull request following the gitrust workflow (~90 min)