Bien démarrer avec VoidPort

Démarrage rapide

Mets ton serveur local en ligne en moins de 2 minutes.

1. 1

   Crée un compte

   Inscris-toi sur voidport.app/register et choisis une offre.

2. 2

   Crée un tunnel dans le dashboard

   Va dans Dashboard > Tunnels > Créer un tunnel. Choisis ce que tu héberges et une région.

C'est tout. Ton serveur est maintenant joignable à l'adresse publique affichée dans le dashboard.

Installation

Sous Windows, l'installateur place voidport.exe dans %LOCALAPPDATA%\VoidPort et l'ajoute à ton PATH. Sous macOS et Linux, il s'installe dans /usr/local/bin, ou dans ~/.local/bin sans root ni sudo.

Téléchargement manuel

Télécharge directement les binaires :

• Linux x64
• Linux ARM64
• Windows x64
• macOS Apple Silicon
• macOS Intel

Vérifier l'installation

$ voidport --version

Créer un tunnel

Depuis le dashboard

1. Connecte-toi à ton dashboard
2. Clique sur « Créer un tunnel »
3. Choisis ce que tu héberges, ou « Port personnalisé » avec TCP, UDP ou les deux
4. Donne-lui un nom (par ex. « minecraft ») et choisis une région (Nuremberg, Helsinki, Ashburn ou Hillsboro)
5. Si le serveur tourne sur une autre machine, indique son hôte cible
6. Clique sur « Créer un tunnel », lance la CLI, puis clique sur « Tester la connexion »

Après la création, le dashboard affiche le token de ton tunnel et la commande pour le lancer. Tu les retrouves à tout moment sur la page du tunnel. Garde le token secret.

Le lancer

Exécute ceci sur la machine qui héberge ton serveur :

$ voidport connect <token>

Rediriger vers un autre port local, juste pour cette fois :

$ voidport connect <token> --port 25566

Lancer plusieurs tunnels dans une seule fenêtre, par exemple jeu et chat vocal :

$ voidport connect <token1> <token2>

Avec la CLI

Tu peux aussi créer et lancer des tunnels depuis le terminal. Il faut pour cela un voidport login unique.

$ voidport login

$ voidport tunnel --preset minecraft-java

voidport up lance tous les tunnels enregistrés sur cette machine, voidport list les affiche.

Autres machines & Docker

Par défaut, la CLI redirige vers l'ordinateur sur lequel elle tourne. Si ton serveur tourne ailleurs, définis l'hôte cible du tunnel : dans le formulaire de création, sur la page du tunnel sous Paramètres, ou avec voidport tunnel --host. La commande de lancement reste voidport connect <token> ; la CLI récupère l'hôte cible toute seule. --host en ligne de commande a la priorité.

L'hôte cible est un nom ou une adresse IP tel que le voit la machine qui exécute la CLI, sans http:// ni port :

Un appareil de ton réseau

Un NAS, un deuxième PC ou un serveur de console sur ton réseau local :

192.168.1.20

nas.local

La machine qui exécute la CLI doit pouvoir le joindre : teste avec ping 192.168.1.20 et vérifie que le serveur accepte les connexions d'autres machines (pas seulement de 127.0.0.1).

Docker

Si la CLI tourne directement sur l'hôte Docker, publie le port du serveur (-p 25565:25565) et laisse l'hôte cible vide.

Si la CLI tourne dans son propre conteneur, dans le même réseau Docker que ton serveur (par exemple comme service dans ton fichier Compose), utilise le nom du conteneur ou du service du serveur comme hôte cible (voir Conteneur Docker) :

mc

Sites web en HTTPS

Les tunnels transmettent du TCP/UDP brut. Un site web en HTTPS affichera un avertissement de certificat, car le navigateur se connecte à <relay>.voidport.net et le certificat est émis pour un autre nom. Le HTTP simple et les serveurs de jeu ne sont pas concernés. HTTPS sur ton propre domaine règle ce problème.

Conteneur Docker

La CLI tourne aussi en conteneur à côté de ton serveur, par exemple dans le même fichier Compose. Rien n'est publié sur l'hôte : les joueurs se connectent via le relay. Crée le tunnel dans le dashboard, puis passe son token et le nom du service du serveur :

services:
  mc:
    image: itzg/minecraft-server
    environment:
      EULA: "TRUE"
    volumes:
      - mc-data:/data

  voidport:
    image: ghcr.io/voidmind-io/voidport:latest
    environment:
      VOIDPORT_TOKEN: ${VOIDPORT_TOKEN}
      VOIDPORT_HOST: mc
    depends_on:
      - mc
    restart: unless-stopped

volumes:
  mc-data:

$ VOIDPORT_TOKEN=<token> docker compose up -d

$ docker compose logs voidport

Le log affiche l'adresse publique. VOIDPORT_TOKEN accepte plusieurs tokens séparés par des virgules (par ex. jeu et chat vocal). VOIDPORT_HOST est le nom du service de ton serveur ; VOIDPORT_PORT remplace le port local du tunnel (un seul token). VOIDPORT_TOKEN_FILE lit le ou les tokens depuis un fichier, par ex. un secret Compose dans /run/secrets/voidport_token. docker compose down déconnecte proprement le tunnel.

Minecraft Bedrock

Avec itzg/minecraft-bedrock-server, crée le tunnel avec le modèle Bedrock. Le log de voidport affiche une ligne server-udp-ports=… : mets sa valeur dans SERVER_UDP_PORTS du service mc et redémarre-le.

SERVER_UDP_PORTS: "<relay IP>:<public port>:19132"

Minecraft sans port

Minecraft Java consulte un enregistrement SRV avant de se connecter, les joueurs n'ont donc pas besoin de taper le port. Donne un nom à ton tunnel et les joueurs rejoignent avec survival.voidport.net au lieu de nbg1.voidport.net:30421.

Définis le nom sur la page du tunnel sous Adresse sans port, dans le formulaire de création quand tu choisis Minecraft: Java Edition, ou avec la CLI :

$ voidport tunnel --preset minecraft-java --address survival

Les noms font 3 à 32 caractères (a-z, 0-9, tirets), premier arrivé, premier servi. Un nouveau nom peut mettre quelques minutes à fonctionner partout. Le nom ne marche que dans Minecraft Java : ce n'est pas une adresse de site web.

Bedrock Edition ne consulte pas les enregistrements SRV. Les joueurs Bedrock ont toujours besoin de l'adresse avec le port.

Ton propre domaine

Pour utiliser un domaine à toi, par ex. play.example.com, crée un enregistrement SRV chez ton fournisseur DNS. La page du tunnel affiche les valeurs exactes et propose un bouton Vérifier. Avec les valeurs de l’exemple :

_minecraft._tcp.play.example.com. 300 IN SRV 0 5 30421 nbg1.voidport.net.

Nom _minecraft._tcp.play (dans la zone example.com), priorité 0, poids 5, le port public de ton tunnel, cible l'hôte relay de ton tunnel. Avec Cloudflare, l'enregistrement doit être en « DNS uniquement ». Si le tunnel change de relay ou de port, mets l'enregistrement à jour.

Vraies IP des joueurs (PROXY protocol)

À travers un tunnel, ton serveur voit toutes les connexions arriver de la machine qui exécute la CLI. Avec le PROXY protocol activé, le relay place la vraie IP et le port du visiteur devant chaque connexion TCP (PROXY protocol v2), pour que les bans, whitelists et logs fonctionnent avec les vraies adresses.

Active-le seulement si ton serveur est configuré pour l'attendre. Un serveur qui n'attend pas l'en-tête refuse toutes les connexions. Tunnels TCP uniquement.

Active-le dans le formulaire de création, sur la page du tunnel sous Paramètres, ou avec voidport tunnel --proxy-protocol pour un nouveau tunnel. Un changement s'applique quand la CLI se reconnecte (redémarre-la). Active-le ensuite dans ton serveur :

Paper (config/paper-global.yml)

proxies:
  proxy-protocol: true

Velocity (velocity.toml, [advanced])

haproxy-protocol = true

BungeeCord / Waterfall (config.yml, sous listeners)

proxy_protocol: true

nginx

listen 8080 proxy_protocol;

Avec Velocity ou BungeeCord, active-le uniquement sur le proxy, pas sur les serveurs derrière. Les serveurs Vanilla et Spigot ne savent pas lire l'en-tête : laisse-le désactivé. Dans nginx, l'adresse se trouve dans $proxy_protocol_addr.

HTTPS sur ton propre domaine

Sers un site web ou une API en https://app.example.com sur le port standard 443, avec un domaine qui t'appartient. Le relay lit uniquement le nom d'hôte demandé par le navigateur (SNI) et transmet la connexion chiffrée telle quelle à ton tunnel ; il ne voit jamais le contenu. Le TLS se termine soit dans la CLI VoidPort, avec un certificat automatique, soit sur ton propre serveur (Caddy, nginx, Traefik, ...).

1. Dans le tableau de bord, sous Domaines, ajoute le nom d'hôte et choisis qui gère le certificat : la CLI VoidPort (automatique) ou ton propre serveur.
2. Chez ton fournisseur DNS, crée l'enregistrement TXT _voidport-challenge.app.example.com avec la valeur affichée et clique sur Vérifier. Garde l'enregistrement TXT : il est revérifié chaque jour. Le nom d'hôte appartient à ton compte : une fois vérifié, il peut passer d'un de tes tunnels à l'autre sans nouvelle vérification.
3. Attribue le nom d'hôte à un tunnel TCP, sur la page Domaines ou dans l'onglet Paramètres du tunnel. Si la CLI gère le TLS, la cible du tunnel est ton serveur HTTP simple (par ex. 3000) ; avec ton propre serveur, son port HTTPS (par ex. 443).
4. Crée un CNAME de app.example.com vers le relay du tunnel (par ex. nbg1.voidport.net). Pour un domaine racine, où le CNAME n'est pas autorisé, utilise plutôt un enregistrement A avec l'IP du relay.

Derrière Cloudflare, mets l'enregistrement en DNS uniquement (nuage gris). Le proxy orange termine lui-même le TLS et n'atteindrait jamais ton serveur. Seuls les domaines qui t'appartiennent sont acceptés, jamais ceux de VoidPort.

Certificats

Avec la CLI VoidPort, rien à faire : dès que le nom d'hôte est vérifié et pointe vers le relay, la CLI obtient un certificat Let's Encrypt et le renouvelle (mets la CLI à jour). Avec ton propre serveur : le port 80 n'est pas transmis, donc le challenge HTTP-01 ne fonctionne pas ; utilise l'une de ces méthodes :

• TLS-ALPN-01 (automatique, à travers le tunnel) : Caddy le fait par défaut dès que HTTP-01 est désactivé. Traefik : un certificate resolver avec tlsChallenge.
• DNS-01 : fonctionne partout (certbot, acme.sh, plugins DNS de Caddy/Traefik).

Caddy (Caddyfile)

{
  # port 80 is not reachable through the tunnel
  auto_https disable_redirects
}

app.example.com {
  tls {
    issuer acme {
      disable_http_challenge
    }
  }
  reverse_proxy localhost:3000
}

Le PROXY protocol fonctionne ici aussi : s'il est activé, la connexion commence par l'en-tête avant le handshake TLS (nginx : listen 443 ssl proxy_protocol;). Le HTTP simple sur le port 80 et les noms d'hôte wildcard ne sont pas pris en charge.

Lancer comme service

Sur un serveur, ou un PC qui doit garder le tunnel actif sans session ouverte, installe la CLI comme service système. Il démarre avec la machine et redémarre tout seul s'il s'arrête.

Linux et macOS

$ sudo voidport service install

Sans noms, il lance tous les tunnels créés sur cette machine avec voidport tunnel. Indique des noms pour en choisir certains (sudo voidport service install mc), ou utilise des tokens du dashboard : sudo voidport service install --token <token>.

Windows

Ouvre PowerShell avec Exécuter en tant qu’administrateur :

$ voidport service install --token <token>

Le gérer

$ voidport service status

$ voidport service logs -f

$ sudo voidport service update

$ sudo voidport service uninstall

Le service utilise sa propre copie de la CLI dans un dossier que seuls les administrateurs peuvent modifier. Après voidport update, lance service update (sous Windows dans un shell administrateur) pour que le service utilise aussi la nouvelle version.

Le service garde les tokens des tunnels dans un fichier lisible uniquement par le service et les administrateurs (/etc/voidport/service.json, sous Windows %ProgramData%\VoidPort). Il n'a pas besoin de ta connexion. Relance service install pour changer les tunnels. Sous Linux, le service utilise systemd et tourne sous l'utilisateur système voidport ; le log est dans le journal. Sous macOS, c'est un daemon launchd qui écrit dans /var/log/voidport.log.

Commandes CLI

$ voidport connect <token> [<token> ...]

$ voidport login

$ voidport tunnel --preset minecraft-java

$ voidport up [<name> ...]

$ sudo voidport service install [<name> ...]

$ voidport list

$ voidport presets

$ voidport relays

$ voidport status [<name>]

$ voidport delete <name>

$ voidport update

TCP ou UDP

Tu hésites ? La plupart des applications utilisent TCP. Minecraft Java utilise TCP, Minecraft Bedrock (1.26.50 et plus) utilise les deux.

Offres & limites

Ports fixes : ton port public reste le même d'une reconnexion à l'autre, les joueurs n'ont donc pas besoin d'une nouvelle adresse.

Dépannage