iemperor/avenger repository overview

⁠Avenger

La vitrine de vos projets open source, à l'écoute de leurs utilisateurs.

Avenger présente vos logiciels libres et recueille les retours de leurs utilisateurs, auto-hébergé, en français :

• Une page par projet : présentation en Markdown (images, vidéos, tableaux), icône, lien vers le code source
• Un wiki par projet, créé avec lui : installation, guides, dépannage
• Trois files de tickets par projet : bugs, retours utilisateurs, demandes de fonctionnalités. Les visiteurs ouvrent un ticket sans créer de compte ; leur e-mail reste privé
• Widget de dépôt de tickets : une ligne de code ajoute un bouton « Signaler un problème » à vos propres applications, prérempli avec l'utilisateur connecté
• Administration : produits publiés ou en brouillon, éditeur Markdown avec aperçu, gestion des tickets (statut, changement de file), code d'intégration du widget prêt à copier
• Plusieurs administrateurs et e-mails : comptes gérés en ligne, service de mail configuré dans l'interface (SMTP avec réglages tout prêts, test pas à pas), notification des nouveaux tickets et suivi par e-mail pour leurs auteurs
• Import / export : un produit passe d'un Avenger à un autre en un fichier (page, icône, wiki et, au choix, les tickets)
• Installation sans configuration : aucune variable obligatoire, un assistant crée le premier administrateur

L'image contient toute l'application : l'interface Angular et l'API Symfony, servies par FrankenPHP⁠ sur le port 8080. Il lui faut seulement une base PostgreSQL, fournie par le fichier Compose ci-dessous.

⁠Tags

Plateforme : linux/amd64. Sources : GitHub⁠, licence MIT.

⁠Installation

⁠1. Le fichier compose.yaml

Dans un dossier vide (mkdir avenger && cd avenger), créez compose.yaml :

# Avenger with its database. No variable is required: docker compose up -d
#   The secrets (database password, application secret, key passphrase) are generated on the first
#   start and kept in the avenger_data volume. Optional settings: see .env.example.
#   Portainer: paste this file as a stack, nothing to enter.
#   Installation code: docker compose logs avenger

x-avenger-environment: &avenger-environment
  # Optional: generated on the first start and kept in /data/secrets when empty
  APP_SECRET: ${APP_SECRET:-}
  JWT_PASSPHRASE: ${JWT_PASSPHRASE:-}
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-}
  # Behind a reverse proxy: its addresses, for the visitors' real IP (rate limits)
  TRUSTED_PROXIES: ${TRUSTED_PROXIES:-}

services:
  # Generates the missing secrets, then stops: the database needs its password first
  init:
    image: iemperor/avenger:${AVENGER_VERSION:-latest}
    command: ["init"]
    environment: *avenger-environment
    volumes:
      - avenger_data:/data
    restart: "no"
    healthcheck:
      disable: true

  avenger:
    image: iemperor/avenger:${AVENGER_VERSION:-latest}
    restart: unless-stopped
    ports:
      - "${AVENGER_PORT:-8080}:8080"
    environment: *avenger-environment
    volumes:
      - avenger_data:/data
    security_opt:
      - no-new-privileges:true
    depends_on:
      database:
        condition: service_healthy

  database:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: avenger
      POSTGRES_USER: avenger
      # Generated by the init service in Avenger's volume, read-only here
      POSTGRES_PASSWORD_FILE: /avenger/secrets/postgres_password
    healthcheck:
      test: ["CMD", "pg_isready", "-d", "avenger", "-U", "avenger"]
      interval: 5s
      timeout: 5s
      retries: 10
    volumes:
      - database_data:/var/lib/postgresql/data
      - avenger_data:/avenger:ro
    depends_on:
      init:
        condition: service_completed_successfully

volumes:
  avenger_data:
  database_data:

Ou téléchargez-le : curl -O https://raw.githubusercontent.com/imperiumclansoftware/avenger/main/docker/compose.yaml

Avec Portainer : Stacks > Add stack, collez ce fichier dans l'éditeur web. Il n'y a rien à saisir dans Environment variables.

⁠2. Démarrage

docker compose up -d
docker compose logs avenger

Au premier démarrage, le service init génère les secrets (mot de passe de la base, secret de l'application, phrase de passe des clés de connexion) dans le volume avenger_data, puis s'arrête. La base démarre avec ce mot de passe, puis Avenger applique les migrations et affiche un code d'installation :

 [OK] Code d'installation : ABCD-EFGH

⁠3. Assistant d'installation

Ouvrez http://<serveur>:8080. L'assistant demande :

1. le code d'installation : il n'est lisible que sur le serveur, le premier venu ne peut donc pas s'attribuer le compte ;
2. l'e-mail et le mot de passe (12 caractères minimum) du premier administrateur.

Vous êtes ensuite connecté à l'administration. Le code est détruit et l'assistant se ferme définitivement. Le code s'obtient aussi avec docker compose exec avenger php bin/console app:setup:code.

⁠Variables d'environnement

Aucune n'est obligatoire. Pour en changer une, créez un fichier .env à côté de compose.yaml (modèle⁠), ou saisissez-la dans la stack Portainer.

Un secret fourni par l'environnement l'emporte sur celui du volume. Sans valeur, le secret conservé dans /data/secrets est utilisé, ou généré au premier démarrage. Un secret existant n'est jamais régénéré.

⁠Données et sauvegarde

Sauvegardez les deux volumes : la base sans avenger_data ne s'ouvre plus, son mot de passe est dans avenger_data.

docker compose stop
docker run --rm -v avenger_avenger_data:/data -v "$PWD":/backup alpine tar -czf /backup/avenger-data.tar.gz -C /data .
docker compose exec -T database pg_dump -U avenger avenger > avenger.sql   # avec la base démarrée
docker compose start

(Le préfixe des volumes, avenger_, est le nom du dossier qui contient compose.yaml.)

⁠HTTPS

L'image sert du HTTP. Pour un accès depuis Internet, placez-la derrière un reverse proxy (Caddy, Traefik, Nginx Proxy Manager…) et renseignez TRUSTED_PROXIES. Exemple avec Caddy :

avenger.example.org {
	reverse_proxy avenger:8080
}

⁠Mise à jour

docker compose pull
docker compose up -d

Les migrations s'appliquent au démarrage ; les secrets, les clés, les icônes et la base sont conservés.

Depuis la 0.1.0, gardez votre .env : son POSTGRES_PASSWORD est celui de votre base. Il est recopié dans le volume au premier démarrage, puis reste utilisé.

⁠Intégrer le widget de tickets

Dans l'administration, l'onglet Intégration de chaque produit donne le code à copier, par exemple :

<script src="https://avenger.example.org/widget.js" data-product="mon-produit" defer></script>

Documentation complète : docs/widget.md⁠.

⁠Détails techniques

• Conteneur : utilisateur sans privilège (www-data), no-new-privileges, aucun secret dans l'image. PHP 8.4.27 minimum (failles PHP2Shell corrigées).
• Démarrage : le conteneur attend la base (2 minutes au plus), applique les migrations, génère les clés de connexion si besoin et vérifie qu'elles s'ouvrent avec leur phrase de passe.
• Santé : GET /api/health (healthcheck de l'image).
• Limites : 10 tickets par quart d'heure et par adresse IP ; 10 essais du code d'installation par quart d'heure et par adresse.
• Autres comptes administrateurs : page Utilisateurs de l'administration, ou docker compose exec avenger php bin/console app:admin:create <e-mail> (mot de passe saisi masqué).

⁠Dépannage