fujin-cli 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

fujin/commands/proxy.py

@@ -0,0 +1,71 @@
+from dataclasses import dataclass
+from typing import Annotated
+
+import cappa
+
+from fujin.commands import BaseCommand
+
+
+@cappa.command(help="Manage web proxy.")
+@dataclass
+class Proxy(BaseCommand):
+    @cappa.command(help="Install the proxy on the remote host")
+    def install(self):
+        with self.connection() as conn:
+            self.create_web_proxy(conn).install()
+
+    @cappa.command(help="Uninstall the proxy from the remote host")
+    def uninstall(self):
+        with self.connection() as conn:
+            self.create_web_proxy(conn).uninstall()
+
+    @cappa.command(help="Start the proxy on the remote host")
+    def start(self):
+        with self.connection() as conn:
+            self.create_web_proxy(conn).start()
+        self.stdout.output("[green]Proxy started successfully![/green]")
+
+    @cappa.command(help="Stop the proxy on the remote host")
+    def stop(self):
+        with self.connection() as conn:
+            self.create_web_proxy(conn).stop()
+        self.stdout.output("[green]Proxy stopped successfully![/green]")
+
+    @cappa.command(help="Restart the proxy on the remote host")
+    def restart(self):
+        with self.connection() as conn:
+            self.create_web_proxy(conn).restart()
+        self.stdout.output("[green]Proxy restarted successfully![/green]")
+
+    @cappa.command(help="Check the status of the proxy on the remote host")
+    def status(self):
+        with self.connection() as conn:
+            self.create_web_proxy(conn).status()
+
+    @cappa.command(help="View the logs of the proxy on the remote host")
+    def logs(self):
+        with self.connection() as conn:
+            self.create_web_proxy(conn).logs()
+
+    @cappa.command(
+        name="export-config",
+        help="Export the proxy configuration file locally to the .fujin directory",
+    )
+    def export_config(
+        self,
+        overwrite: Annotated[
+            bool, cappa.Arg(help="overwrite any existing config file")
+        ] = False,
+    ):
+        with self.connection() as conn:
+            proxy = self.create_web_proxy(conn)
+            if proxy.config_file.exists() and not overwrite:
+                self.stdout.output(
+                    f"[blue]{proxy.config_file} already exists, use --overwrite to overwrite it content.[/blue]"
+                )
+            else:
+                self.config.local_config_dir.mkdir(exist_ok=True)
+                proxy.export_config()
+                self.stdout.output(
+                    f"[green]Config file successfully to {proxy.config_file}[/green]"
+                )

fujin/commands/prune.py

@@ -0,0 +1,42 @@
+from dataclasses import dataclass
+from typing import Annotated
+
+import cappa
+from rich.prompt import Confirm
+
+from fujin.commands import BaseCommand
+
+
+@cappa.command(
+    help="Prune old version artifacts, keeping only the specified number of recent versions"
+)
+@dataclass
+class Prune(BaseCommand):
+    keep: Annotated[
+        int,
+        cappa.Arg(
+            short="-k",
+            long="--keep",
+            help="Number of version artifacts to retain (minimum 1)",
+        ),
+    ] = 2
+
+    def __call__(self):
+        if self.keep < 1:
+            raise cappa.Exit("The minimum value for the --keep option is 1", code=1)
+        with self.connection() as conn, conn.cd(self.app_dir):
+            result = conn.run(
+                f"sed -n '{self.keep + 1},$p' .versions", hide=True
+            ).stdout.strip()
+            result_list = result.split("\n")
+            if result == "":
+                self.stdout.output("[blue]No versions to prune[/blue]")
+                return
+            if not Confirm.ask(
+                f"[red]The following versions will be permanently deleted: {', '.join(result_list)}. This action is irreversible. Are you sure you want to proceed?[/red]"
+            ):
+                return
+            to_prune = [f"{self.app_dir}/v{v}" for v in result_list]
+            conn.run(f"rm -r {' '.join(to_prune)}", warn=True)
+            conn.run(f"sed -i '{self.keep + 1},$d' .versions", warn=True)
+            self.stdout.output("[green]Pruning completed successfully[/green]")

fujin/commands/redeploy.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import hashlib
+
+import cappa
+
+from fujin.commands import BaseCommand
+from .deploy import Deploy
+
+
+@cappa.command(help="Redeploy the application to apply code and environment changes")
+class Redeploy(BaseCommand):
+    def __call__(self):
+        deploy = Deploy()
+        deploy.build_app()
+        local_requirements = hashlib.md5(
+            self.config.requirements.read_bytes()
+        ).hexdigest()
+        with self.app_environment() as conn:
+            hook_manager = self.create_hook_manager(conn)
+            hook_manager.pre_deploy()
+            current_host_version = conn.run(
+                "head -n 1 .versions", warn=True, hide=True
+            ).stdout.strip()
+            try:
+                host_requirements = (
+                    conn.run(
+                        f"md5sum v{current_host_version}/requirements.txt",
+                        warn=True,
+                        hide=True,
+                    )
+                    .stdout.strip()
+                    .split()[0]
+                )
+                skip_requirements = host_requirements == local_requirements
+            except IndexError:
+                skip_requirements = False
+            deploy.transfer_files(conn, skip_requirements=skip_requirements)
+            if skip_requirements and current_host_version != self.config.version:
+                conn.run(
+                    f"cp v{current_host_version}/requirements.txt  {deploy.versioned_assets_dir}/requirements.txt "
+                )
+            deploy.install_project(conn, skip_setup=skip_requirements)
+            deploy.release(conn)
+            self.create_process_manager(conn).restart_services()
+            deploy.update_version_history(conn)
+            hook_manager.post_deploy()
+            self.stdout.output("[green]Redeployment completed successfully![/green]")

fujin/commands/rollback.py

@@ -0,0 +1,49 @@
+from dataclasses import dataclass
+
+import cappa
+from rich.prompt import Prompt, Confirm
+
+from fujin.commands import BaseCommand
+from fujin.commands.deploy import Deploy
+
+
+@cappa.command(help="Rollback application to a previous version")
+@dataclass
+class Rollback(BaseCommand):
+    def __call__(self):
+        with self.app_environment() as conn:
+            result = conn.run(
+                "sed -n '2,$p' .versions", warn=True, hide=True
+            ).stdout.strip()
+            if not result:
+                self.stdout.output("[blue]No rollback targets available")
+                return
+            versions: list[str] = result.split("\n")
+            try:
+                version = Prompt.ask(
+                    "Enter the version you want to rollback to:",
+                    choices=versions,
+                    default=versions[0],
+                )
+            except KeyboardInterrupt as e:
+                raise cappa.Exit("Rollback aborted by user.", code=0) from e
+
+            current_app_version = conn.run(
+                "head -n 1 .versions", warn=True, hide=True
+            ).stdout.strip()
+            versions_to_clean = [current_app_version] + versions[
+                : versions.index(version)
+            ]
+            confirm = Confirm.ask(
+                f"[blue]Rolling back to v{version} will permanently delete versions {', '.join(versions_to_clean)}. This action is irreversible. Are you sure you want to proceed?[/blue]"
+            )
+            if not confirm:
+                return
+            deploy = Deploy()
+            deploy.install_project(conn, version)
+            self.create_process_manager(conn).restart_services()
+            conn.run(f"rm -r {' '.join(f'v{v}' for v in versions_to_clean)}", warn=True)
+            conn.run(f"sed -i '1,/{version}/{{/{version}/!d}}' .versions", warn=True)
+            self.stdout.output(
+                f"[green]Rollback to version {version} from {current_app_version} completed successfully![/green]"
+            )

fujin/commands/secrets.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass
+
+import cappa
+
+from fujin.commands import BaseCommand
+
+
+@cappa.command(help="")
+@dataclass
+class Secrets(BaseCommand):
+    pass

fujin/commands/server.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import secrets
+from functools import partial
+from typing import Annotated
+
+import cappa
+
+from fujin.commands import BaseCommand
+
+
+@cappa.command(help="Manage server operations")
+class Server(BaseCommand):
+    @cappa.command(help="Display information about the host system")
+    def info(self):
+        with self.connection() as conn:
+            result = conn.run(f"command -v fastfetch", warn=True, hide=True)
+            if result.ok:
+                conn.run("fastfetch", pty=True)
+            else:
+                self.stdout.output(conn.run("cat /etc/os-release", hide=True).stdout)
+
+    @cappa.command(help="Setup uv, web proxy, and install necessary dependencies")
+    def bootstrap(self):
+        with self.connection() as conn:
+            hook_manager = self.create_hook_manager(conn)
+            hook_manager.pre_bootstrap()
+            conn.run("sudo apt update && sudo apt upgrade -y", pty=True)
+            conn.run("sudo apt install -y sqlite3 curl rsync", pty=True)
+            result = conn.run("command -v uv", warn=True)
+            if not result.ok:
+                conn.run("curl -LsSf https://astral.sh/uv/install.sh | sh")
+                conn.run("uv tool update-shell")
+            conn.run("uv tool install fastfetch-bin-edge")
+            self.create_web_proxy(conn).install()
+            hook_manager.post_bootstrap()
+            self.stdout.output(
+                "[green]Server bootstrap completed successfully![/green]"
+            )
+
+    @cappa.command(help="Stop and uninstall the web proxy")
+    def uninstall_proxy(self):
+        with self.connection() as conn:
+            self.create_web_proxy(conn).uninstall()
+
+    @cappa.command(
+        help="Execute an arbitrary command on the server, optionally in interactive mode"
+    )
+    def exec(
+        self,
+        command: str,
+        interactive: Annotated[bool, cappa.Arg(default=False, short="-i")],
+        appenv: Annotated[
+            bool,
+            cappa.Arg(
+                default=False,
+                long="--appenv",
+                help="Change to app directory and enable app environment",
+            ),
+        ],
+    ):
+        context = self.app_environment() if appenv else self.connection()
+        with context as conn:
+            if interactive:
+                conn.run(command, pty=interactive, warn=True)
+            else:
+                self.stdout.output(conn.run(command, hide=True).stdout)
+
+    @cappa.command(
+        name="create-user", help="Create a new user with sudo and ssh access"
+    )
+    def create_user(
+        self,
+        name: str,
+        with_password: Annotated[bool, cappa.Arg(long="--with-password")] = False,
+    ):
+        with self.connection() as conn:
+            run_pty = partial(conn.run, pty=True)
+            run_pty(
+                f"sudo adduser --disabled-password --gecos '' {name}",
+            )
+            run_pty(f"sudo mkdir -p /home/{name}/.ssh")
+            run_pty(f"sudo cp ~/.ssh/authorized_keys /home/{name}/.ssh/")
+            run_pty(f"sudo chown -R {name}:{name} /home/{name}/.ssh")
+            if with_password:
+                password = secrets.token_hex(8)
+                run_pty(f"echo '{name}:{password}' | sudo chpasswd")
+                self.stdout.output(f"[green]Generated password: [/green]{password}")
+            run_pty(f"sudo chmod 700 /home/{name}/.ssh")
+            run_pty(f"sudo chmod 600 /home/{name}/.ssh/authorized_keys")
+            run_pty(f"echo '{name} ALL=(ALL) NOPASSWD:ALL' | sudo tee -a /etc/sudoers")
+            self.stdout.output(f"[green]New user {name} created successfully![/green]")

fujin/commands/up.py

@@ -0,0 +1,15 @@
+import cappa
+from fujin.commands import BaseCommand
+
+from .deploy import Deploy
+from .server import Server
+
+
+@cappa.command(help="Run everything required to deploy an application to a fresh host.")
+class Up(BaseCommand):
+    def __call__(self):
+        Server().bootstrap()
+        Deploy()()
+        self.stdout.output(
+            "[green]Server bootstrapped and application deployed successfully![/green]"
+        )

fujin/config.py

@@ -0,0 +1,290 @@
+"""
+Fujin uses a ``fujin.toml`` file at the root of your project for configuration. Below are all available configuration options.
+
+app
+---
+The name of your project or application. Must be a valid Python package name.
+
+app_bin
+-------
+Path to your application's executable. Used by the **app** subcommand for remote execution.
+Default: ``.venv/bin/{app}``
+
+version
+--------
+The version of your project to build and deploy. If not specified, automatically parsed from ``pyproject.toml`` under ``project.version``.
+
+python_version
+--------------
+The Python version for your virtualenv. If not specified, automatically parsed from ``.python-version`` file.
+
+versions_to_keep
+----------------
+The number of versions to keep on the host. After each deploy, older versions are pruned based on this setting. By default, it keeps the latest 5 versions,
+set this to `None` to never automatically prune.
+
+build_command
+-------------
+The command to use to build your project's distribution file.
+
+distfile
+--------
+Path to your project's distribution file. This should be the main artifact containing everything needed to run your project on the server.
+Supports version placeholder, e.g., ``dist/app_name-{version}-py3-none-any.whl``
+
+release_command
+---------------
+Optional command to run at the end of deployment (e.g., database migrations).
+
+requirements
+------------
+Path to your requirements file.
+Default: ``requirements.txt``
+
+Webserver
+---------
+
+type
+~~~~
+The reverse proxy implementation to use. Available options:
+
+- ``fujin.proxies.caddy`` (default)
+- ``fujin.proxies.nginx``
+- ``fujin.proxies.dummy`` (disables proxy functionality)
+
+upstream
+~~~~~~~~
+The address where your web application listens for requests. Supports any value compatible with your chosen web proxy:
+
+- HTTP address (e.g., ``localhost:8000``)
+- Unix socket (e.g., ``unix//run/project.sock``)
+
+statics
+~~~~~~~
+
+Defines the mapping of URL paths to local directories for serving static files. The syntax and support for static
+file serving depend on the selected reverse proxy.
+
+Example:
+
+.. code-block:: toml
+
+    [webserver]
+    upstream = "unix//run/project.sock"
+    type = "fujin.proxies.caddy"
+    statics = { "/static/*" = "/var/www/example.com/static/" }
+
+processes
+---------
+
+A mapping of process names to commands that will be managed by the process manager. Define as many processes as needed, but
+when using any proxy other than ``fujin.proxies.dummy``, a ``web`` process must be declared.  Refer to the ``apps_dir``
+setting on the host to understand how ``app_dir`` is determined.
+
+Example:
+
+.. code-block:: toml
+
+    [processes]
+    web = ".venv/bin/gunicorn myproject.wsgi:application"
+
+
+.. note::
+
+    Commands are relative to your ``app_dir``. When generating systemd service files, the full path is automatically constructed.
+
+Host Configuration
+-------------------
+
+ip
+~~
+The IP address or hostname of the remote host.
+
+domain_name
+~~~~~~~~~~~
+The domain name pointing to this host. Used for web proxy configuration.
+
+user
+~~~~
+The login user for running remote tasks. Should have passwordless sudo access for optimal operation.
+
+.. note::
+
+    You can create a user with these requirements using the ``fujin server create-user`` command.
+
+envfile
+~~~~~~~
+Path to the production environment file that will be copied to the host.
+
+apps_dir
+~~~~~~~~
+
+Base directory for project storage on the host. Path is relative to user's home directory.
+Default: ``.local/share/fujin``. This value determines your project's ``app_dir``, which is ``{apps_dir}/{app}``.
+
+password_env
+~~~~~~~~~~~~
+
+Environment variable containing the user's password. Only needed if the user cannot run sudo without a password.
+
+ssh_port
+~~~~~~~~
+
+SSH port for connecting to the host.
+Default: ``22``
+
+key_filename
+~~~~~~~~~~~~
+
+Path to the SSH private key file for authentication. Optional if using your system's default key location.
+
+aliases
+-------
+
+A mapping of shortcut names to Fujin commands. Allows you to create convenient shortcuts for commonly used commands.
+
+Example:
+
+.. code-block:: toml
+
+    [aliases]
+    console = "app exec -i shell_plus" # open an interactive django shell
+    dbconsole = "app exec -i dbshell" # open an interactive django database shell
+    shell = "server exec --appenv -i bash" # SSH into the project directory with environment variables loaded
+
+
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import msgspec
+
+from .errors import ImproperlyConfiguredError
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+from .hooks import HooksDict
+
+
+class Config(msgspec.Struct, kw_only=True):
+    app_name: str = msgspec.field(name="app")
+    app_bin: str = ".venv/bin/{app}"
+    version: str = msgspec.field(default_factory=lambda: read_version_from_pyproject())
+    versions_to_keep: int | None = 5
+    python_version: str = msgspec.field(default_factory=lambda: find_python_version())
+    build_command: str
+    release_command: str | None = None
+    skip_project_install: bool = False
+    distfile: str
+    aliases: dict[str, str] = msgspec.field(default_factory=dict)
+    host: HostConfig
+    processes: dict[str, str] = msgspec.field(default_factory=dict)
+    process_manager: str = "fujin.process_managers.systemd"
+    webserver: Webserver
+    _requirements: str = msgspec.field(name="requirements", default="requirements.txt")
+    hooks: HooksDict = msgspec.field(default_factory=dict)
+    local_config_dir: Path = Path(".fujin")
+
+    def __post_init__(self):
+        self.app_bin = self.app_bin.format(app=self.app_name)
+        # self._distfile = self._distfile.format(version=self.version)
+
+        if "web" not in self.processes and self.webserver.type != "fujin.proxies.dummy":
+            raise ValueError(
+                "Missing web process or set the proxy to 'fujin.proxies.dummy' to disable the use of a proxy"
+            )
+
+    @property
+    def requirements(self) -> Path:
+        return Path(self._requirements)
+
+    def get_distfile_path(self, version: str | None = None) -> Path:
+        version = version or self.version
+        return Path(self.distfile.format(version=version))
+
+    @classmethod
+    def read(cls) -> Config:
+        fujin_toml = Path("fujin.toml")
+        if not fujin_toml.exists():
+            raise ImproperlyConfiguredError(
+                "No fujin.toml file found in the current directory"
+            )
+        try:
+            return msgspec.toml.decode(fujin_toml.read_text(), type=cls)
+        except msgspec.ValidationError as e:
+            raise ImproperlyConfiguredError(f"Improperly configured, {e}") from e
+
+
+class HostConfig(msgspec.Struct, kw_only=True):
+    ip: str
+    domain_name: str
+    user: str
+    _envfile: str = msgspec.field(name="envfile")
+    apps_dir: str = ".local/share/fujin"
+    password_env: str | None = None
+    ssh_port: int = 22
+    _key_filename: str | None = msgspec.field(name="key_filename", default=None)
+
+    def __post_init__(self):
+        self.apps_dir = f"/home/{self.user}/{self.apps_dir}"
+
+    def to_dict(self):
+        d = {f: getattr(self, f) for f in self.__struct_fields__}
+        d.pop("_key_filename")
+        d.pop("_envfile")
+        d["key_filename"] = self.key_filename
+        d["envfile"] = self.envfile
+        return d
+
+    @property
+    def envfile(self) -> Path:
+        return Path(self._envfile)
+
+    @property
+    def key_filename(self) -> Path | None:
+        if self._key_filename:
+            return Path(self._key_filename)
+
+    @property
+    def password(self) -> str | None:
+        if not self.password_env:
+            return
+        password = os.getenv(self.password_env)
+        if not password:
+            msg = f"Env {self.password_env} can not be found"
+            raise ImproperlyConfiguredError(msg)
+        return password
+
+    def get_app_dir(self, app_name: str) -> str:
+        return f"{self.apps_dir}/{app_name}"
+
+
+class Webserver(msgspec.Struct):
+    upstream: str
+    type: str = "fujin.proxies.caddy"
+    statics: dict[str, str] = msgspec.field(default_factory=dict)
+
+
+def read_version_from_pyproject():
+    try:
+        return tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+    except (FileNotFoundError, KeyError) as e:
+        raise msgspec.ValidationError(
+            "Project version was not found in the pyproject.toml file, define it manually"
+        ) from e
+
+
+def find_python_version():
+    py_version_file = Path(".python-version")
+    if not py_version_file.exists():
+        raise msgspec.ValidationError(
+            f"Add a python_version key or a .python-version file"
+        )
+    return py_version_file.read_text().strip()

fujin/connection.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from functools import partial
+from typing import TYPE_CHECKING
+
+import cappa
+from fabric import Connection
+from invoke import Responder
+from invoke.exceptions import UnexpectedExit
+from paramiko.ssh_exception import (
+    AuthenticationException,
+    NoValidConnectionsError,
+    SSHException,
+)
+
+if TYPE_CHECKING:
+    from fujin.config import HostConfig
+
+
+def _get_watchers(host: HostConfig) -> list[Responder]:
+    if not host.password:
+        return []
+    return [
+        Responder(
+            pattern=r"\[sudo\] password:",
+            response=f"{host.password}\n",
+        ),
+        Responder(
+            pattern=rf"\[sudo\] password for {host.user}:",
+            response=f"{host.password}\n",
+        ),
+    ]
+
+
+@contextmanager
+def host_connection(host: HostConfig) -> Connection:
+    connect_kwargs = None
+    if host.key_filename:
+        connect_kwargs = {"key_filename": str(host.key_filename)}
+    elif host.password:
+        connect_kwargs = {"password": host.password}
+    conn = Connection(
+        host.ip,
+        user=host.user,
+        port=host.ssh_port,
+        connect_kwargs=connect_kwargs,
+    )
+    try:
+        conn.run = partial(
+            conn.run,
+            env={
+                "PATH": f"/home/{host.user}/.cargo/bin:/home/{host.user}/.local/bin:$PATH"
+            },
+            watchers=_get_watchers(host),
+        )
+        yield conn
+    except AuthenticationException as e:
+        msg = f"Authentication failed for {host.user}@{host.ip} -p {host.ssh_port}.\n"
+        if host.key_filename:
+            msg += f"An SSH key was provided at {host.key_filename.resolve()}. Please verify its validity and correctness."
+        elif host.password:
+            msg += f"A password was provided through the environment variable {host.password_env}. Please ensure it is correct for the user {host.user}."
+        else:
+            msg += "No password or SSH key was provided. Ensure your current host has SSH access to the target host."
+        raise cappa.Exit(msg, code=1) from e
+    except (UnexpectedExit, NoValidConnectionsError) as e:
+        raise cappa.Exit(str(e), code=1) from e
+    except SSHException as e:
+        raise cappa.Exit(
+            f"{e}, possible causes: incorrect user, or either you or the server may be offline",
+            code=1,
+        ) from e
+    finally:
+        conn.close()