fujin-cli 0.25.2__tar.gz → 0.26.0__tar.gz

{fujin_cli-0.25.2 → fujin_cli-0.26.0}/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.26.0] - 2026-06-05
+
+### 🚀 Features
+
+- Hooks system
+- Improve reliability
+
+### ⚡ Performance
+
+- Ssh and deploy units cache
+
 ## [0.25.2] - 2026-03-31
 
 ### 🚀 Features

{fujin_cli-0.25.2 → fujin_cli-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fujin-cli
-Version: 0.25.2
+Version: 0.26.0
 Summary: Get your project up and running in a few minutes on your own vps.
 Project-URL: Documentation, https://github.com/Tobi-De/fujin#readme
 Project-URL: Issues, https://github.com/Tobi-De/fujin/issues

{fujin_cli-0.25.2 → fujin_cli-0.26.0}/docs/configuration.rst

@@ -177,6 +177,77 @@ For static files (Django example):
 
 The ``{app_dir}`` variable is substituted during deployment.
 
+Hooks
+-----
+
+Deployment hooks let you run custom commands at specific points during the deploy and rollback lifecycle. They are defined in the ``[hooks]`` section of ``fujin.toml``.
+
+Hook Phases
+~~~~~~~~~~~
+
+**pre-install**
+    Runs before the installer, as the deploy (SSH) user. Use for infrastructure setup like installing packages or creating databases. Has access to environment variables from ``.env``. **Failure is fatal** — the deploy stops and rolls back.
+
+    .. code-block:: toml
+        :caption: fujin.toml
+
+        [hooks]
+        pre_install = [
+            "sudo apt-get install -y postgresql",
+            "sudo -u postgres createdb myapp",
+        ]
+
+**post-install**
+    Runs after the package is installed but before systemd services are started. Executes as ``app_user`` via ``sudo -u``, within the app's environment (``.appenv`` sourced, so the app binary is on ``PATH``). Use for database migrations. **Failure is fatal** — the deploy stops.
+
+    .. code-block:: toml
+        :caption: fujin.toml
+
+        [hooks]
+        post_install = [
+            "python manage.py migrate --noinput",
+        ]
+
+**post-start**
+    Runs after services are confirmed running, before Caddy configuration. Executes as ``app_user`` within the app environment. Use for static file collection, cache warming, or health checks. **Failure is non-fatal** — services are already running, a warning is logged but the deploy succeeds.
+
+    .. code-block:: toml
+        :caption: fujin.toml
+
+        [hooks]
+        post_start = [
+            "python manage.py collectstatic --noinput",
+        ]
+
+Available Variables
+~~~~~~~~~~~~~~~~~~
+
+Hook commands support the same template variables as systemd unit files:
+
+- ``{app_name}`` - Application name
+- ``{app_dir}`` - Full path to application directory (``/opt/fujin/{app_name}``)
+- ``{app_user}`` - User running the app
+- ``{version}`` - Current version being deployed
+- ``{install_dir}`` - Path to ``.install`` directory
+
+Complete Example
+~~~~~~~~~~~~~~~~
+
+.. code-block:: toml
+    :caption: fujin.toml
+
+    [hooks]
+    pre_install = [
+        "sudo -u postgres createdb myapp",
+    ]
+    post_install = [
+        "python manage.py migrate --noinput",
+    ]
+    post_start = [
+        "python manage.py collectstatic --noinput",
+        "python manage.py clearsessions",
+    ]
+
 Host Configuration
 -------------------
 

{fujin_cli-0.25.2 → fujin_cli-0.26.0}/justfile

@@ -1,4 +1,4 @@
-set dotenv-load := true
+set dotenv-load
 
 # List all available commands
 _default:

{fujin_cli-0.25.2 → fujin_cli-0.26.0}/plugins/fujin-secrets-1password/pyproject.toml

@@ -4,7 +4,7 @@ requires = [ "uv-build>=0.9.18,<0.10" ]
 
 [project]
 name = "fujin-secrets-1password"
-version = "0.25.2"
+version = "0.26.0"
 description = "1Password secret adapter for Fujin"
 readme = "README.md"
 authors = [
@@ -20,7 +20,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "fujin-cli>=0.25.2",
+  "fujin-cli>=0.26",
   "python-dotenv>=1.0.1",
 ]
 

{fujin_cli-0.25.2 → fujin_cli-0.26.0}/plugins/fujin-secrets-bitwarden/pyproject.toml

@@ -4,7 +4,7 @@ requires = [ "uv-build>=0.9.18,<0.10" ]
 
 [project]
 name = "fujin-secrets-bitwarden"
-version = "0.25.2"
+version = "0.26.0"
 description = "Bitwarden secret adapter for Fujin"
 readme = "README.md"
 authors = [
@@ -20,7 +20,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "fujin-cli>=0.25.2",
+  "fujin-cli>=0.26",
   "python-dotenv>=1.0.1",
 ]
 

{fujin_cli-0.25.2 → fujin_cli-0.26.0}/plugins/fujin-secrets-doppler/pyproject.toml

@@ -4,7 +4,7 @@ requires = [ "uv-build>=0.9.18,<0.10" ]
 
 [project]
 name = "fujin-secrets-doppler"
-version = "0.25.2"
+version = "0.26.0"
 description = "Doppler secret adapter for Fujin"
 readme = "README.md"
 authors = [
@@ -20,7 +20,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "fujin-cli>=0.25.2",
+  "fujin-cli>=0.26",
   "python-dotenv>=1.0.1",
 ]
 

{fujin_cli-0.25.2 → fujin_cli-0.26.0}/plugins/fujin-secrets-env/pyproject.toml

@@ -4,7 +4,7 @@ requires = [ "uv-build>=0.9.18,<0.10" ]
 
 [project]
 name = "fujin-secrets-env"
-version = "0.25.2"
+version = "0.26.0"
 description = "Environment variable secret adapter for Fujin"
 readme = "README.md"
 authors = [
@@ -20,7 +20,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "fujin-cli>=0.25.2",
+  "fujin-cli>=0.26",
   "python-dotenv>=1.0.1",
 ]
 

{fujin_cli-0.25.2 → fujin_cli-0.26.0}/pyproject.toml

@@ -5,7 +5,7 @@ requires = [ "hatchling" ]
 
 [project]
 name = "fujin-cli"
-version = "0.25.2"
+version = "0.26.0"
 description = "Get your project up and running in a few minutes on your own vps."
 readme = "README.md"
 keywords = [
@@ -151,7 +151,7 @@ markers = [
 ]
 
 [tool.bumpversion]
-current_version = "0.25.2"
+current_version = "0.26.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = [ "{major}.{minor}.{patch}" ]
 search = "{current_version}"

fujin_cli-0.26.0/src/fujin/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.26.0"

{fujin_cli-0.25.2 → fujin_cli-0.26.0}/src/fujin/_installer.py

@@ -13,7 +13,7 @@ import sys
 import tempfile
 import time
 import zipfile
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from itertools import chain
 from pathlib import Path
 from typing import Literal, TypedDict
@@ -62,6 +62,7 @@ class InstallConfig:
     caddy_config_path: str
     app_bin: str
     deployed_units: list[DeployedUnit]
+    hooks: dict[str, list[str]] = field(default_factory=dict)
 
     @property
     def uv_path(self) -> str:
@@ -102,6 +103,30 @@ def _setup_logging(verbose: int) -> None:
     logger.setLevel(level)
 
 
+def _run_hooks(config: InstallConfig, phase: str, *, fatal: bool = True) -> None:
+    commands = config.hooks.get(phase, [])
+    if not commands:
+        return
+
+    logger.info("Running %s hooks...", phase)
+    install_dir = f"{config.app_dir}/.install"
+    for cmd in commands:
+        logger.info("  [%s] %s", phase, cmd)
+        full_cmd = f"sudo -u {shlex.quote(config.app_user)} bash -c " + shlex.quote(
+            f"source {install_dir}/.appenv 2>/dev/null ; {cmd}"
+        )
+        try:
+            run(full_cmd, check=True, timeout=300)
+        except subprocess.TimeoutExpired:
+            if fatal:
+                raise
+            logger.warning("[%s] Hook timed out: %s", phase, cmd)
+        except subprocess.CalledProcessError as e:
+            if fatal:
+                raise
+            logger.warning("[%s] Hook failed (exit %d): %s", phase, e.returncode, cmd)
+
+
 def install(
     config: InstallConfig, bundle_dir: Path, *, full_restart: bool = False
 ) -> None:
@@ -226,6 +251,11 @@ export -f {config.app_name}
     run(f"chown {config.deploy_user}:{config.app_user} {app_dir}")
     app_dir.chmod(0o775)
 
+    # ==========================================================================
+    # PHASE 2.5: POST-INSTALL HOOKS
+    # ==========================================================================
+    _run_hooks(config, "post_install", fatal=True)
+
     # ==========================================================================
     # PHASE 3: CONFIGURING SYSTEMD SERVICES
     # ==========================================================================
@@ -350,6 +380,35 @@ export -f {config.app_name}
         if unit["template_timer_name"]:
             active_units.append(unit["template_timer_name"])
 
+    # Validate all unit files before enabling/starting (catch errors early)
+    logger.info("Validating systemd unit files...")
+    validation_issues = 0
+    for unit in config.deployed_units:
+        unit_path = SYSTEMD_SYSTEM_DIR / unit["template_service_name"]
+        if not unit_path.exists():
+            continue
+        result = subprocess.run(
+            f"systemd-analyze verify {shlex.quote(str(unit_path))}",
+            shell=True,
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0 or result.stderr.strip():
+            validation_issues += 1
+            logger.warning(
+                "Validation issues in %s (exit code %d):",
+                unit_path.name,
+                result.returncode,
+            )
+            for line in result.stderr.splitlines():
+                logger.warning("  %s", line)
+
+    if validation_issues:
+        logger.warning(
+            "%d unit(s) have validation warnings - review above before continuing",
+            validation_issues,
+        )
+
     units_str = " ".join(active_units)
     run(
         f"systemctl daemon-reload && systemctl enable {units_str}",
@@ -423,6 +482,11 @@ export -f {config.app_name}
             )
         sys.exit(EXIT_SERVICE_START_FAILED)
 
+    # ==========================================================================
+    # PHASE 3.5: POST-START HOOKS
+    # ==========================================================================
+    _run_hooks(config, "post_start", fatal=False)
+
     # ==========================================================================
     # PHASE 4: CADDY CONFIGURATION
     # ==========================================================================

{fujin_cli-0.25.2 → fujin_cli-0.26.0}/src/fujin/commands/deploy.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import base64
 import json
 import logging
 import shlex
@@ -25,6 +24,7 @@ from fujin.audit import log_operation
 from fujin.commands import BaseCommand
 from fujin.commands.rollback import Rollback
 from fujin.config import get_git_short_hash
+from fujin.connection import SSH2Connection
 from fujin.errors import (
     BuildError,
     CommandError,
@@ -94,7 +94,26 @@ class Deploy(BaseCommand):
         try:
             logger.debug("Build command: %s", self.config.build_command)
             self.output.info(f"Building application ...")
-            subprocess.run(self.config.build_command, check=True, shell=True)
+            subprocess.run(
+                self.config.build_command,
+                check=True,
+                shell=True,
+                timeout=self.config.build_timeout,
+            )
+        except subprocess.TimeoutExpired:
+            self.output.error(
+                f"Build command timed out after {self.config.build_timeout}s"
+            )
+            self.output.info(
+                f"Command: {self.config.build_command}\n\n"
+                "Troubleshooting:\n"
+                "  - The build is taking too long; increase build_timeout in fujin.toml\n"
+                "  - Check for infinite loops or hung subprocesses in your build\n"
+                "  - Try running the build command manually to see its progress"
+            )
+            raise BuildError(
+                "Build timed out", command=self.config.build_command
+            ) from None
         except subprocess.CalledProcessError as e:
             self.output.error(f"Build command failed with exit code {e.returncode}")
             self.output.info(
@@ -274,6 +293,23 @@ class Deploy(BaseCommand):
                 all_unresolved.update(unresolved)
                 (zipapp_dir / "Caddyfile").write_text(resolved_caddyfile)
 
+            # Resolve hook commands
+            resolved_hooks: dict[str, list[str]] = {}
+            if self.config.hooks_config:
+                for phase in (
+                    "pre_install",
+                    "post_install",
+                    "post_start",
+                ):
+                    commands = getattr(self.config.hooks_config, phase)
+                    resolved_commands = []
+                    for cmd in commands:
+                        resolved, unresolved = safe_format(cmd, **context)
+                        all_unresolved.update(unresolved)
+                        resolved_commands.append(resolved)
+                    if resolved_commands:
+                        resolved_hooks[phase] = resolved_commands
+
             if all_unresolved:
                 self.output.warning(
                     f"Found unresolved variables in configuration files: {', '.join(sorted(all_unresolved))}\n"
@@ -295,6 +331,7 @@ class Deploy(BaseCommand):
                 "caddy_config_path": self.config.caddy_config_path,
                 "app_bin": self.config.app_name,  # Just the binary name, not full path
                 "deployed_units": deployed_units_data,
+                "hooks": resolved_hooks,
             }
 
             # Write config without indent for smaller size
@@ -325,7 +362,7 @@ class Deploy(BaseCommand):
             min_rsync_size = 30 * 1024 * 1024
 
             # Upload and Execute
-            with self.connection() as conn:
+            with self._deploy_session() as conn:
                 # Check rsync availability while creating the directory (single round trip)
                 # Only check if bundle is large enough to benefit from rsync
                 if bundle_size >= min_rsync_size:
@@ -367,43 +404,67 @@ class Deploy(BaseCommand):
 
                 self.output.success("Bundle uploaded successfully.")
 
+                self.output.info("Executing remote installation...")
+
                 # Write .env file directly (not bundled for security)
                 remote_env_path = f"{self.config.install_dir}/.env"
                 remote_env_path_q = shlex.quote(remote_env_path)
                 install_dir_q = shlex.quote(self.config.install_dir)
+                remote_env_backup_q = shlex.quote(f"{remote_env_path}.bak")
                 logger.debug("Writing .env to %s", remote_env_path)
 
-                # Use base64 encoding to safely transfer content with special chars
-                encoded_env = base64.b64encode(resolved_env.encode()).decode()
-                # chown may fail on first deploy if app_user doesn't exist yet
-                # (installer creates it), so use || true to make it non-fatal
-                write_env_cmd = (
+                # Backup existing .env (ensure install dir exists first)
+                conn.run(
                     f"mkdir -p {install_dir_q} && "
-                    f"echo {shlex.quote(encoded_env)} | base64 -d > {remote_env_path_q} && "
-                    f"chmod 640 {remote_env_path_q} && "
-                    f"(chown {self.selected_host.user}:{self.config.app_user} {remote_env_path_q} || true)"
+                    f"cp {remote_env_path_q} {remote_env_backup_q} 2>/dev/null || true",
+                    hide=True,
                 )
 
                 if self.restart_on_env_change:
-                    # Wrap command to capture old hash before writing and output it after
                     new_env_hash = hashlib.sha256(resolved_env.encode()).hexdigest()
-                    cmd = (
-                        f"OLD=$(sha256sum {remote_env_path_q} 2>/dev/null | cut -d' ' -f1 || true) && "
-                        f"{write_env_cmd} && "
-                        f'echo ":::ENV_HASH:::$OLD:::ENV_HASH:::"'
+                    old_hash_output, _ = conn.run(
+                        f"sha256sum {remote_env_path_q} 2>/dev/null | cut -d' ' -f1 || true",
+                        hide=True,
                     )
-                    output, _ = conn.run(cmd, hide=True)
-                    # Extract hash from between markers
-                    old_env_hash = output.split(":::ENV_HASH:::")[1]
+                    old_env_hash = old_hash_output.strip()
                     if old_env_hash and old_env_hash != new_env_hash:
                         self.output.info(
                             "Environment variables changed, forcing full restart..."
                         )
                         self.full_restart = True
-                else:
-                    conn.run(write_env_cmd, hide=True)
 
-                self.output.info("Executing remote installation...")
+                # Upload .env via SCP (avoids shell escaping issues with base64 piping)
+                with tempfile.NamedTemporaryFile(mode="w", suffix=".env") as tmp_env:
+                    tmp_env.write(resolved_env)
+                    tmp_env.flush()
+                    conn.put(tmp_env.name, remote_env_path_q)
+
+                # chown may fail on first deploy if app_user doesn't exist yet
+                # (installer creates it), so use || true to make it non-fatal
+                conn.run(
+                    f"chmod 640 {remote_env_path_q} && "
+                    f"(chown {self.selected_host.user}:{self.config.app_user} {remote_env_path_q} || true)",
+                    hide=True,
+                )
+
+                # Run pre-install hooks (as deploy user, with .env sourced)
+                pre_install_commands = resolved_hooks.get("pre_install", [])
+                if pre_install_commands:
+                    self.output.info("Running pre-install hooks...")
+                    try:
+                        for cmd in pre_install_commands:
+                            self.output.info(f"  [pre-install] {cmd}")
+                            full_cmd = (
+                                f"set -a; source {install_dir_q}/.env 2>/dev/null; set +a; "
+                                f"{cmd}"
+                            )
+                            conn.run(full_cmd, pty=True)
+                    except CommandError:
+                        conn.run(
+                            f"mv {remote_env_backup_q} {remote_env_path_q} 2>/dev/null || true",
+                            hide=True,
+                        )
+                        raise
 
                 rollback_ran = False
                 rollback_succeeded = False
@@ -416,15 +477,24 @@ class Deploy(BaseCommand):
                     conn.run(install_cmd, pty=True)
                 except CommandError as e:
                     if e.code != installer.EXIT_SERVICE_START_FAILED:
+                        conn.run(f"rm -f {remote_env_backup_q}", warn=True, hide=True)
                         raise DeploymentError(
                             f"Installation failed with exit code {e.code}"
                         ) from e
 
                     if self.no_rollback:
+                        conn.run(f"rm -f {remote_env_backup_q}", warn=True, hide=True)
                         raise DeploymentError(
                             "Services failed to start. Rollback disabled via --no-rollback."
                         ) from e
 
+                    # Restore previous .env before rollback
+                    self.output.info("Restoring previous environment...")
+                    conn.run(
+                        f"mv {remote_env_backup_q} {remote_env_path_q} 2>/dev/null || true",
+                        hide=True,
+                    )
+
                     rollback = Rollback(host=self.host, previous=True, strict=True)
                     self.output.info(
                         "Services failed to start. Rolling back to previous version."
@@ -458,6 +528,9 @@ class Deploy(BaseCommand):
                         warn=True,
                     )
 
+                if not rollback_ran:
+                    conn.run(f"rm -f {remote_env_backup_q}", warn=True, hide=True)
+
                 # Get git commit hash if available
                 log_operation(
                     connection=conn,
@@ -497,6 +570,34 @@ class Deploy(BaseCommand):
             with tempfile.TemporaryDirectory() as tmpdir:
                 yield Path(tmpdir)
 
+    @contextmanager
+    def _deploy_session(self) -> Generator[SSH2Connection, None, None]:
+        """Context manager that combines SSH connection + deployment lock.
+
+        Acquires the deploy lock on the remote server before yielding the
+        connection, and releases it on exit (even on error).
+        """
+        with self.connection() as conn:
+            install_dir_q = shlex.quote(self.config.install_dir)
+            lock_file_q = shlex.quote(f"{self.config.install_dir}/.deploy_lock")
+            conn.run(f"mkdir -p {install_dir_q}", hide=True)
+            _, acquired = conn.run(
+                f"(set -C; echo $$ > {lock_file_q}) 2>/dev/null",
+                warn=True,
+                hide=True,
+            )
+            if not acquired:
+                raise DeploymentError(
+                    "Another deployment is in progress.\n"
+                    "If you are sure no deploy is running, remove the lock manually:\n"
+                    f"  ssh {self.selected_host.user}@{self.selected_host.address} rm {lock_file_q}"
+                )
+
+            try:
+                yield conn
+            finally:
+                conn.run(f"rm -f {lock_file_q}", warn=True, hide=True)
+
     def _show_deployment_summary(self, bundle_size: int, bundle_version: str):
         console = Console()
 

{fujin_cli-0.25.2 → fujin_cli-0.26.0}/src/fujin/config.py

@@ -1,5 +1,5 @@
 from __future__ import annotations
-from functools import cache
+from functools import cache, cached_property
 
 import os
 import subprocess
@@ -45,13 +45,20 @@ class SecretConfig(msgspec.Struct):
             )
 
 
-class Config(msgspec.Struct, kw_only=True):
+class HooksConfig(msgspec.Struct):
+    pre_install: list[str] = msgspec.field(default_factory=list)
+    post_install: list[str] = msgspec.field(default_factory=list)
+    post_start: list[str] = msgspec.field(default_factory=list)
+
+
+class Config(msgspec.Struct, kw_only=True, dict=True):
     app_name: str = msgspec.field(name="app")
     app_user: str | None = None  # User to run the app as (defaults to app_name)
     version: str = msgspec.field(default_factory=lambda: read_version_from_pyproject())
     versions_to_keep: int | None = 5
     python_version: str | None = None
     build_command: str
+    build_timeout: int = 300
     installation_mode: InstallationMode
     distfile: str
     aliases: dict[str, str] = msgspec.field(default_factory=dict)
@@ -70,6 +77,11 @@ class Config(msgspec.Struct, kw_only=True):
         default_factory=lambda: SecretConfig(adapter="system"),
     )
 
+    hooks_config: HooksConfig | None = msgspec.field(
+        name="hooks",
+        default=None,
+    )
+
     def __post_init__(self):
         if not self.app_user:
             self.app_user = self.app_name
@@ -187,7 +199,7 @@ class Config(msgspec.Struct, kw_only=True):
     def caddy_config_path(self) -> str:
         return f"{self.caddy_config_dir}/{self.app_name}.caddy"
 
-    @property
+    @cached_property
     def deployed_units(self) -> list[DeployedUnit]:
         return discover_deployed_units(
             self.local_config_dir, self.app_name, self.replicas