elektromail 0.1.1

A minimal, Rust-based IMAP + SMTP mail server for local development and testing
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

# GitLab CI Setup & Validation

This document describes how to run and validate the GitLab CI pipeline for elektromail,
including Docker integration tests, multi-platform image publishing, and crates.io publishing.

## 1) Prerequisites

- The repository root has `.gitlab-ci.yml` that includes `.gitlab/gitlab-ci.yml`.
- GitLab Container Registry is enabled for the project.
- A Docker-capable runner is available (see below).

## 2) Runner Requirements

The pipeline uses Docker-in-Docker (DinD) and multi-arch buildx. The runner must allow:

- Docker executor (or a Kubernetes executor with DinD enabled)
- Privileged mode (required for `tonistiigi/binfmt` and buildx multi-arch)

If you use a self-managed runner, set `privileged = true` in the runner config.

## 3) Required CI Variables

Set these in **Project → Settings → CI/CD → Variables**:

- `CRATES_IO_TOKEN` (masked, protected if you only publish from tags)

GitLab automatically provides these for registry publishing:

- `CI_REGISTRY`, `CI_REGISTRY_USER`, `CI_REGISTRY_PASSWORD`

## 4) Pipeline Triggers

- **Merge Request or default branch** runs:
  - `test` (fmt, clippy, tests)
  - `test:docker` (container integration test)
  - security jobs (deny, sbom, etc.)
  - `docker:build` on default branch (pushes latest + branch tags)

- **Tag release** `vX.Y.Z`:
  - `docker:build` publishes multi-platform images with `vX.Y.Z` and `latest`
  - `publish:crates` is **manual** on tag (requires click in GitLab UI)

## 5) Validation Checklist (Step-by-Step)

1. Push a branch or open a Merge Request.
2. Go to **CI/CD → Pipelines** and open the latest pipeline.
3. Verify these jobs succeed:
   - `test`
   - `test:docker`
4. Check `test:docker` logs for:
   - `docker build -t elektromail:ci .`
   - `cargo test docker_procedere_smoke`
   - `ELEKTROMAIL_DOCKER_HOST=docker` (required for DinD connectivity)
5. Merge to default branch (or push directly).
6. Verify `docker:build` completes on default branch.
7. Confirm images appear in **Deploy → Container Registry**:
   - `latest`
   - `<branch>`
   - `<short SHA>`
8. Create a tag `vX.Y.Z` and push:
   - `docker:build` should publish `vX.Y.Z`
   - `publish:crates` appears as manual
9. Trigger `publish:crates` from the job UI.
10. Confirm the crate appears on crates.io with the tag version.

## 6) Troubleshooting

- **buildx fails or binfmt missing**: runner likely not privileged.
- **docker:build can’t push**: check registry credentials and project registry settings.
- **container_scanning can’t find image**: ensure `docker:build` ran and pushed the image tag used by `CS_IMAGE`.
- **publish:crates fails**: verify `CRATES_IO_TOKEN` and `Cargo.toml` version.