docs: add Windows build and run guide / and fix(postgres): resolve pg_dump/pg_restore path cross-platform

.github/workflows/windows-release.yml

@@ -0,0 +1,99 @@
+name: Build Windows release
+
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+    branches:
+      - main
+      - master
+
+jobs:
+  build-windows:
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Rust toolchain (MSVC)
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable-x86_64-pc-windows-msvc
+          profile: minimal
+          override: true
+
+      - name: Install vcpkg and OpenSSL (x64)
+        shell: pwsh
+        run: |
+          # Install vcpkg and the prebuilt OpenSSL package
+          git clone https://github.com/microsoft/vcpkg C:\vcpkg
+          C:\vcpkg\bootstrap-vcpkg.bat
+          C:\vcpkg\vcpkg install openssl:x64-windows
+          # Export variables for subsequent steps
+          'VCPKG_ROOT=C:\vcpkg' | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+          'OPENSSL_DIR=C:\vcpkg\installed\x64-windows' | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+
+      - name: Build (cargo release)
+        shell: pwsh
+        env:
+          # Cargo / openssl-sys will pick up OPENSSL_DIR from the environment
+          OPENSSL_DIR: ${{ env.OPENSSL_DIR }}
+        run: |
+          # Ensure the environment variable is present for this step
+          if (-Not $env:OPENSSL_DIR) { Write-Host "OPENSSL_DIR not set, printing env for debugging"; Get-ChildItem Env: | ForEach-Object { Write-Host $_ } }
+          cargo build --release
+
+      - name: Prepare artifact zip
+        id: prepare_artifact
+        shell: pwsh
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          $tag = $env:RELEASE_TAG
+          if (-not $tag) { $tag = $env:GITHUB_SHA }
+
+          # Find the built executable. Prefer an explicit portabase-agent.exe, fall back to first exe in target/release
+          $exe = "target\release\portabase-agent.exe"
+          if (-not (Test-Path $exe)) {
+            $first = Get-ChildItem -Path target\release -Filter *.exe | Select-Object -First 1
+            if ($first) { $exe = $first.FullName }
+          }
+
+          if (-not (Test-Path $exe)) { Write-Error "Built binary not found in target/release"; exit 1 }
+
+          $outDir = "artifact"
+          New-Item -ItemType Directory -Path $outDir -Force | Out-Null
+          Copy-Item -Path $exe -Destination $outDir\
+
+          $zipName = "windows-release-$tag.zip"
+          if (Test-Path $zipName) { Remove-Item $zipName }
+          Compress-Archive -Path "$outDir\*" -DestinationPath $zipName -Force
+          Write-Host "ZIP=$zipName"
+          Write-Output "zip=$zipName" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows-release
+          path: windows-release-*.zip
+
+      - name: Create GitHub Release
+        if: startsWith(github.ref, 'refs/tags/')
+        id: create_release
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: ${{ github.ref_name }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload release asset
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: actions/upload-release-asset@v1
+        with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: windows-release-${{ github.ref_name }}.zip
+          asset_name: windows-release-${{ github.ref_name }}.zip
+          asset_content_type: application/zip

.gitignore

@@ -6,4 +6,5 @@
 .env
 
 .claude
-/docs
+
+/docs

CITATION.cff

@@ -27,5 +27,5 @@ keywords:
   - self-hosted
   - portabase
 license: Apache-2.0
-version: 1.12.1
+version: 1.12.2
 date-released: '2026-02-24'

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "portabase-agent"
-version = "1.12.1"
+version = "1.12.2"
 edition = "2024"
 
 [dependencies]

docker-compose.yml

@@ -19,7 +19,7 @@ services:
       APP_ENV: development
       LOG: debug
       TZ: "Europe/Paris"
-      EDGE_KEY: "eyJzZXJ2ZXJVcmwiOiJodHRwOi8vbG9jYWxob3N0Ojg4ODciLCJhZ2VudElkIjoiMGZiNDYyMmUtMTMxNS00MzMxLTlkMTMtZWMzMjAyZjZiNTIwIiwibWFzdGVyS2V5QjY0IjoiMUh0djdtWCtYVkJxL0IzUEV2WDlZZjlQeUdVZW5oRHlXemo5THRqNW90WT0ifQ=="
+      EDGE_KEY: "eyJzZXJ2ZXJVcmwiOiJodHRwOi8vbG9jYWxob3N0Ojg4ODciLCJhZ2VudElkIjoiNWRkZTE1NTctZWQ1ZC00MjUxLThiZDMtMDE0MjkxOTg2OGZjIiwibWFzdGVyS2V5QjY0IjoiQlhWM1hvbEM2NTZTVjdkTmdjV1BHUWxrKytycExJNmxHRGk3Q1BCNWllbz0ifQ=="
       #CHUNK_SIZE_MB: "1"
       #POOLING: 1
       #DATABASES_CONFIG_FILE: "config.toml"

src/domain/postgres/backup.rs

@@ -1,4 +1,5 @@
 use anyhow::Result;
+use std::collections::HashMap;
 use std::path::PathBuf;
 use std::process::Command;
 use std::sync::Arc;
@@ -13,6 +14,7 @@ pub async fn run(
     cfg: DatabaseConfig,
     format: PostgresDumpFormat,
     backup_dir: PathBuf,
+    env: HashMap<String, String>,
     logger: Arc<JobLogger>,
 ) -> Result<PathBuf> {
     tokio::task::spawn_blocking(move || -> Result<PathBuf> {
@@ -37,18 +39,18 @@ pub async fn run(
                 logger.log("info", format!("Running FC backup for {}", cfg.name));
 
                 let file_path = backup_dir.join(format!("{}.dump", cfg.generated_id));
-                let url = format!(
-                    "postgresql://{}:{}@{}:{}/{}",
-                    cfg.username, cfg.password, cfg.host, cfg.port, cfg.database
-                );
 
                 let start = Instant::now();
                 let output = Command::new(&pg_dump)
-                    .arg("--dbname").arg(&url)
+                    .arg("--host").arg(&cfg.host)
+                    .arg("--port").arg(cfg.port.to_string())
+                    .arg("--username").arg(&cfg.username)
+                    .arg("--dbname").arg(&cfg.database)
                     .arg("-Fc")
                     .arg("-f").arg(&file_path)
                     .arg("-v")
                     .arg("--compress=3")
+                    .envs(env)
                     .output();
                 let duration_ms = start.elapsed().as_millis() as f64;
 
@@ -87,19 +89,19 @@ pub async fn run(
                     return Err(e.into());
                 }
 
-                let url = format!(
-                    "postgresql://{}:{}@{}:{}/{}",
-                    cfg.username, cfg.password, cfg.host, cfg.port, cfg.database
-                );
-                let cmd_label = format!("pg_dump -Fd {}", url);
+                let cmd_label = format!("pg_dump -Fd {}@{}:{}/{}", cfg.username, cfg.host, cfg.port, cfg.database);
 
                 let start = Instant::now();
                 let output = Command::new(&pg_dump)
-                    .arg("--dbname").arg(&url)
+                    .arg("--host").arg(&cfg.host)
+                    .arg("--port").arg(cfg.port.to_string())
+                    .arg("--username").arg(&cfg.username)
+                    .arg("--dbname").arg(&cfg.database)
                     .arg("-Fd")
                     .arg("-j").arg("4")
                     .arg("-f").arg(&dump_dir)
                     .arg("-v")
+                    .envs(env)
                     .output();
                 let duration_ms = start.elapsed().as_millis() as f64;
 

src/domain/postgres/connection.rs

@@ -1,18 +1,23 @@
 use crate::domain::postgres::format::PostgresDumpFormat;
 use crate::services::config::DatabaseConfig;
+use crate::settings::CONFIG;
 use anyhow::Result;
 use std::path::Path;
-use tokio_postgres::{Client, NoTls};
+use tokio_postgres::{Client, Config, NoTls};
 use tracing::{error, info};
 
 pub async fn connect(cfg: &DatabaseConfig) -> Result<Client> {
     info!("Connecting to postgres database {}:{}", cfg.host, cfg.port);
-    let dsn = format!(
-        "host={} port={} user={} password={} dbname={}",
-        cfg.host, cfg.port, cfg.username, cfg.password, cfg.database
-    );
 
-    let (client, connection) = tokio_postgres::connect(&dsn, NoTls).await?;
+    let mut config = Config::new();
+    config
+        .host(&cfg.host)
+        .port(cfg.port)
+        .user(&cfg.username)
+        .password(&cfg.password)
+        .dbname(&cfg.database);
+
+    let (client, connection) = config.connect(NoTls).await?;
     tokio::spawn(async move {
         if let Err(e) = connection.await {
             error!("Postgres connection error: {}", e);
@@ -28,11 +33,91 @@ pub async fn server_version(cfg: &DatabaseConfig) -> Result<String> {
     Ok(version)
 }
 
+/// Resolves the `bin` directory of a PostgreSQL installation for the given
+/// major version, in a cross-platform way.
+///
+/// Resolution order:
+/// 1. The `PG_BIN_DIR` environment variable, if set, is used as-is. This
+///    allows users/CI to override detection for non-standard installs
+///    (e.g. portable PostgreSQL distributions, custom install locations).
+/// 2. Platform-specific default install locations (Debian/Ubuntu packages,
+///    the official Windows installer, Homebrew/Postgres.app on macOS, and
+///    common RPM-based layouts on other Linux distros).
+/// 3. A `PATH` lookup for `pg_dump` (`pg_dump.exe` on Windows), returning
+///    its parent directory.
+/// 4. The historical Debian/Ubuntu path as a last-resort fallback, so the
+///    function keeps returning a `PathBuf` (never panics) even when nothing
+///    was found, preserving the previous behavior for callers.
+///
+/// The override is sourced from `CONFIG.pg_bin_dir` (the `PG_BIN_DIR`
+/// environment variable). An empty value means "unset" and falls through to
+/// detection.
 pub fn select_pg_path(version: &str) -> std::path::PathBuf {
+    select_pg_path_with(version, &CONFIG.pg_bin_dir)
+}
+
+/// Inner resolver behind [`select_pg_path`], parameterized over the
+/// `PG_BIN_DIR` override. Kept pure (no env / no `CONFIG` access) so it is
+/// unit-testable without mutating process-global state.
+pub(crate) fn select_pg_path_with(version: &str, pg_bin_dir: &str) -> std::path::PathBuf {
     let major = version.split('.').next().unwrap_or("17");
+
+    if !pg_bin_dir.is_empty() {
+        return pg_bin_dir.into();
+    }
+
+    let candidates: Vec<std::path::PathBuf> = if cfg!(target_os = "windows") {
+        vec![
+            // Default install path used by the official EDB Windows installer
+            format!(r"C:\Program Files\PostgreSQL\{major}\bin").into(),
+            format!(r"C:\Program Files (x86)\PostgreSQL\{major}\bin").into(),
+        ]
+    } else if cfg!(target_os = "macos") {
+        vec![
+            // Homebrew on Apple Silicon
+            format!("/opt/homebrew/opt/postgresql@{major}/bin").into(),
+            // Homebrew on Intel
+            format!("/usr/local/opt/postgresql@{major}/bin").into(),
+            // Postgres.app
+            format!("/Applications/Postgres.app/Contents/Versions/{major}/bin").into(),
+        ]
+    } else {
+        vec![
+            // Debian/Ubuntu packages
+            format!("/usr/lib/postgresql/{major}/bin").into(),
+            // Common RPM-based distro layout
+            format!("/usr/pgsql-{major}/bin").into(),
+        ]
+    };
+
+    if let Some(found) = candidates.into_iter().find(|p| pg_dump_exists_in(p)) {
+        return found;
+    }
+
+    if let Some(dir) = find_pg_dump_in_path() {
+        return dir;
+    }
+
     format!("/usr/lib/postgresql/{}/bin", major).into()
 }
 
+pub(crate) fn pg_dump_binary_name() -> &'static str {
+    if cfg!(target_os = "windows") {
+        "pg_dump.exe"
+    } else {
+        "pg_dump"
+    }
+}
+
+pub(crate) fn pg_dump_exists_in(dir: &std::path::Path) -> bool {
+    dir.join(pg_dump_binary_name()).is_file()
+}
+
+fn find_pg_dump_in_path() -> Option<std::path::PathBuf> {
+    let path_var = std::env::var_os("PATH")?;
+    std::env::split_paths(&path_var).find(|dir| pg_dump_exists_in(dir))
+}
+
 pub async fn terminate_connections(cfg: &DatabaseConfig) -> Result<()> {
     let mut admin = cfg.clone();
     admin.database = "postgres".to_string().into();
@@ -68,6 +153,7 @@ pub async fn detect_format_from_size(cfg: &DatabaseConfig) -> PostgresDumpFormat
         "Detecting database format {:?} - {:?}",
         cfg.name, cfg.generated_id
     );
+
     let client = match connect(cfg).await {
         Ok(c) => c,
         Err(_) => return PostgresDumpFormat::Fc,

src/domain/postgres/database.rs

@@ -1,8 +1,9 @@
 use anyhow::Result;
 use async_trait::async_trait;
+use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
-
+use tracing::info;
 use super::{backup, format::PostgresDumpFormat, ping, restore};
 use crate::domain::factory::Database;
 use crate::services::backup::logger::JobLogger;
@@ -18,6 +19,13 @@ impl PostgresDatabase {
     pub fn new(cfg: DatabaseConfig, format: PostgresDumpFormat) -> Self {
         Self { cfg, format }
     }
+
+    fn build_env(&self) -> HashMap<String, String> {
+        let mut envs = std::env::vars().collect::<HashMap<_, _>>();
+        envs.insert("PGPASSWORD".to_string(), self.cfg.password.to_string());
+        info!("envs: {:?}", envs);
+        envs
+    }
 }
 
 #[async_trait]
@@ -35,14 +43,28 @@ impl Database for PostgresDatabase {
 
     async fn backup(&self, dir: &Path, logger: Arc<JobLogger>) -> Result<PathBuf> {
         FileLock::acquire(&self.cfg.generated_id, DbOpLock::Backup.as_str()).await?;
-        let res = backup::run(self.cfg.clone(), self.format, dir.to_path_buf(), logger).await;
+        let res = backup::run(
+            self.cfg.clone(),
+            self.format,
+            dir.to_path_buf(),
+            self.build_env(),
+            logger,
+        )
+        .await;
         FileLock::release(&self.cfg.generated_id).await?;
         res
     }
 
     async fn restore(&self, file: &Path, logger: Arc<JobLogger>) -> Result<()> {
         FileLock::acquire(&self.cfg.generated_id, DbOpLock::Restore.as_str()).await?;
-        let res = restore::run(self.cfg.clone(), self.format, file.to_path_buf(), logger).await;
+        let res = restore::run(
+            self.cfg.clone(),
+            self.format,
+            file.to_path_buf(),
+            self.build_env(),
+            logger,
+        )
+        .await;
         FileLock::release(&self.cfg.generated_id).await?;
         res
     }

src/domain/postgres/mod.rs

@@ -1,5 +1,5 @@
 pub mod backup;
-mod connection;
+pub(crate) mod connection;
 pub mod database;
 mod format;
 mod ping;