arcsecond 4.4.1__tar.gz → 4.4.3__tar.gz

{arcsecond-4.4.1 → arcsecond-4.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: arcsecond
-Version: 4.4.1
+Version: 4.4.3
 Summary: CLI for arcsecond.io
 Project-URL: Homepage, https://github.com/arcsecond-io/cli
 Project-URL: Issues, https://github.com/arcsecond-io/cli/issues

{arcsecond-4.4.1 → arcsecond-4.4.3}/arcsecond/hosting/composedoc.py

@@ -34,6 +34,7 @@ from .local import (
 MARKER_START = re.compile(r"^\s*# >>> arcsecond:(\S+)\s*$")
 MARKER_END = re.compile(r"^\s*# <<< arcsecond:(\S+)\s*$")
 ENV_REF = re.compile(r"\$\{([A-Z_][A-Z0-9_]*)(?::-[^}]*)?\}")
+ENV_DEFAULT = re.compile(r"^\$\{[A-Z_][A-Z0-9_]*:-([^}]*)\}$")
 
 
 @dataclass
@@ -58,6 +59,12 @@ def _strip_comment(line: str) -> str:
     return line.strip().lstrip("#").strip()
 
 
+def _as_shipped(value: str) -> str:
+    """A `${VAR:-default}` value as an installation that leaves VAR unset runs it."""
+    match = ENV_DEFAULT.match(value)
+    return match.group(1) if match else value
+
+
 class _Reader:
     """Walks the template line by line, keeping the comments."""
 
@@ -134,7 +141,7 @@ class _Reader:
             "stop_grace_period": "stop_grace_period",
         }
         if key in scalar:
-            setattr(self.current, scalar[key], value)
+            setattr(self.current, scalar[key], _as_shipped(value))
         elif key == "healthcheck":
             self.current.healthcheck = True
         elif key == "ports" and value.startswith("["):
@@ -226,7 +233,8 @@ ENV_KEYS: Dict[str, tuple] = {
         OPERATOR,
         "The address other computers reach the installation at, port included (e.g. 192.168.1.42:5555). The backend "
         "builds invitation and password-reset links from it. Empty means localhost:5555. "
-        "Set with `arcsecond setup --lan-host`.",
+        "`arcsecond setup` fills it in with this machine's network address when it is empty; "
+        "set it with `arcsecond setup --lan-host`.",
     ),
     OPTIONAL_SERVICES_ENV_KEY: (
         SETUP,
@@ -288,6 +296,28 @@ ENV_KEYS: Dict[str, tuple] = {
         OPERATOR,
         "How many jobs the data worker runs at once. Default 2; each can hold a few hundred MB.",
     ),
+    "ARCSECOND_API_IMAGE": (
+        OPERATOR,
+        "The image the backend, both workers, beat and the alerts consumer run instead of the published one: "
+        "one built from the backend's sources, e.g. `arcsecond-api:latest`. Empty: the published image. Set "
+        "ARCSECOND_API_PULL_POLICY to `never` with it, then `arcsecond restart`.",
+    ),
+    "ARCSECOND_API_PULL_POLICY": (
+        OPERATOR,
+        "`never` when ARCSECOND_API_IMAGE names an image that exists on this machine only, so `arcsecond update` "
+        "and `arcsecond start --pull` leave it alone rather than fail to download it. Default `missing`.",
+    ),
+    "ARCSECOND_WEB_IMAGE": (
+        OPERATOR,
+        "The image the web interface runs instead of the published one: one built from the webapp's sources, "
+        "e.g. `arcsecond-web:latest`. Empty: the published image. Set ARCSECOND_WEB_PULL_POLICY to `never` "
+        "with it, then `arcsecond restart web`.",
+    ),
+    "ARCSECOND_WEB_PULL_POLICY": (
+        OPERATOR,
+        "`never` when ARCSECOND_WEB_IMAGE names an image that exists on this machine only, as "
+        "ARCSECOND_API_PULL_POLICY does for the backend's. Default `missing`.",
+    ),
 }
 
 

{arcsecond-4.4.1 → arcsecond-4.4.3}/arcsecond/hosting/docker/docker-compose.yml

@@ -1,6 +1,6 @@
 # === Arcsecond.local config. ===
 # *** DO NOT change any name or port number. ***
-# Version 7.4
+# Version 7.5
 
 services:
   # Database (PostgresQL)
@@ -29,7 +29,12 @@ services:
 
   # Arcsecond backend (REST APIs). Can be used for API calls and external pipelines, scripts etc.
   backend:
-    image: ghcr.io/arcsecond-io/arcsecond-api:latest
+    # ARCSECOND_API_IMAGE swaps the published image for one built from the
+    # backend's sources, here and on every service below that runs it.
+    # ARCSECOND_API_PULL_POLICY=never goes with it: such an image exists on
+    # this machine only, and `arcsecond update` must not try to download it.
+    image: ${ARCSECOND_API_IMAGE:-ghcr.io/arcsecond-io/arcsecond-api:latest}
+    pull_policy: ${ARCSECOND_API_PULL_POLICY:-missing}
     container_name: arcsecond-api
     restart: unless-stopped
     entrypoint: /home/app/entrypoint-server.sh
@@ -72,7 +77,8 @@ services:
   # Arcsecond worker, for offloading background work: the Control Room's
   # exposures and procedures, and everything else someone is waiting on.
   worker:
-    image: ghcr.io/arcsecond-io/arcsecond-api:latest
+    image: ${ARCSECOND_API_IMAGE:-ghcr.io/arcsecond-io/arcsecond-api:latest}
+    pull_policy: ${ARCSECOND_API_PULL_POLICY:-missing}
     container_name: arcsecond-worker
     restart: unless-stopped
     entrypoint: /home/app/entrypoint-worker.sh
@@ -100,7 +106,8 @@ services:
   # storages, database backups, keograms, catalogue refreshes. On its own
   # queue, so a long zip can never hold up a frame the observer is waiting for.
   dataworker:
-    image: ghcr.io/arcsecond-io/arcsecond-api:latest
+    image: ${ARCSECOND_API_IMAGE:-ghcr.io/arcsecond-io/arcsecond-api:latest}
+    pull_policy: ${ARCSECOND_API_PULL_POLICY:-missing}
     container_name: arcsecond-dataworker
     restart: unless-stopped
     entrypoint: /home/app/entrypoint-worker.sh
@@ -126,7 +133,8 @@ services:
 
   # Arcsecond beat, to launch specific background tasks at specific times.
   beat:
-    image: ghcr.io/arcsecond-io/arcsecond-api:latest
+    image: ${ARCSECOND_API_IMAGE:-ghcr.io/arcsecond-io/arcsecond-api:latest}
+    pull_policy: ${ARCSECOND_API_PULL_POLICY:-missing}
     container_name: arcsecond-beat
     restart: unless-stopped
     entrypoint: /home/app/entrypoint-beat.sh
@@ -149,7 +157,10 @@ services:
   # organisation-based and therefore always a portal, so the second port that
   # used to be here (5577) served the very same app.
   web:
-    image: ghcr.io/arcsecond-io/arcsecond-web:latest
+    # ARCSECOND_WEB_IMAGE and ARCSECOND_WEB_PULL_POLICY: the same as the
+    # backend's pair above, for an image built from the webapp's sources.
+    image: ${ARCSECOND_WEB_IMAGE:-ghcr.io/arcsecond-io/arcsecond-web:latest}
+    pull_policy: ${ARCSECOND_WEB_PULL_POLICY:-missing}
     container_name: arcsecond-web
     restart: unless-stopped
     depends_on:
@@ -183,7 +194,8 @@ services:
   # GCN_CONSUMER_CLIENT_SECRET in .env; idles harmlessly when they are absent.
   # Single instance only — do not scale it.
   alerts:
-    image: ghcr.io/arcsecond-io/arcsecond-api:latest
+    image: ${ARCSECOND_API_IMAGE:-ghcr.io/arcsecond-io/arcsecond-api:latest}
+    pull_policy: ${ARCSECOND_API_PULL_POLICY:-missing}
     container_name: arcsecond-alerts
     restart: unless-stopped
     entrypoint: /home/app/entrypoint-alerts.sh

{arcsecond-4.4.1 → arcsecond-4.4.3}/arcsecond/hosting/doctor.py

@@ -58,6 +58,7 @@ from .local import (
     REQUIRED_ENV_PROVIDERS,
     template_versions,
 )
+from .utils import lan_ipv4
 
 OK, WARN, FAIL, SKIP = "ok", "warn", "fail", "skip"
 
@@ -236,14 +237,7 @@ class Host:
         return parse_ss(result.stdout)
 
     def lan_ipv4(self) -> Optional[str]:
-        # No packet is sent: connecting a UDP socket only picks the interface
-        # the default route would use, and that is the address to hand around.
-        try:
-            with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
-                s.connect(("10.255.255.255", 1))
-                return s.getsockname()[0]
-        except OSError:
-            return None
+        return lan_ipv4()
 
     def http_ok(self, url: str) -> Optional[int]:
         try:

{arcsecond-4.4.1 → arcsecond-4.4.3}/arcsecond/hosting/local.py

@@ -15,7 +15,9 @@ from .utils import (
     _get_encryption_key,
     _get_random_postgres_password,
     _get_random_secret_key,
+    _read_env_value,
     _set_env_value,
+    lan_ipv4,
 )
 
 ENV_FILENAME = ".env"
@@ -113,7 +115,8 @@ REQUIRED_ENV_PROVIDERS = {
     # Empty placeholders: the operator pastes their own GCN credentials here.
     "GCN_CONSUMER_CLIENT_ID": lambda: "",
     "GCN_CONSUMER_CLIENT_SECRET": lambda: "",
-    # Empty placeholder: set by `arcsecond setup --lan-host`, or by hand.
+    # Empty placeholder: filled in by `setup` with this machine's LAN address
+    # (_fill_in_lan_host), or set by `arcsecond setup --lan-host`, or by hand.
     FRONTEND_HOST_ENV_KEY: lambda: "",
 }
 
@@ -500,6 +503,30 @@ def _normalise_lan_host(value):
     return value
 
 
+# What `--lan-host ""` writes. Spelled out rather than left empty, so that the
+# next `setup` does not take an empty value for "never decided" and declare the
+# LAN address over the operator's choice.
+THIS_MACHINE_ONLY_HOST = "localhost:5555"
+
+
+def _fill_in_lan_host(env_path):
+    """Declare this machine's LAN address when no address is declared yet.
+
+    Left empty, every invitation and password-reset link the server emails
+    says localhost, which only works on this machine. A value already there,
+    whoever wrote it, is never touched: `doctor` is what notices when a
+    declared IP no longer matches the machine.
+    """
+    if (_read_env_value(FRONTEND_HOST_ENV_KEY, env_path) or "").strip():
+        return None
+    detected = lan_ipv4()
+    if not detected or detected.startswith("127."):
+        return None
+    host = _normalise_lan_host(detected)
+    _set_env_value(env_path, FRONTEND_HOST_ENV_KEY, host)
+    return host
+
+
 @click.command(short_help="Prepare the installation of Arcsecond.local.")
 @click.option(
     "--with-alerts/--without-alerts",
@@ -515,7 +542,9 @@ def _normalise_lan_host(value):
     metavar="HOST[:PORT]",
     help="The address other computers reach this machine at (e.g. "
     "192.168.1.42 or arcsecond.local). Needed for invitation and "
-    "password-reset links to work from other computers. Port defaults to 5555.",
+    "password-reset links to work from other computers. Port defaults to 5555. "
+    "Without it, setup declares this machine's network address when none is "
+    "declared yet; an empty value keeps the links on this machine.",
 )
 @click.option(
     "--with-sky-map/--without-sky-map",
@@ -549,12 +578,19 @@ def setup(with_alerts, lan_host, with_sky_map):
     for name, answer in to_record:
         _record_optional_service_decision(env_path, name, answer)
     if lan_host is not None:
-        host = _normalise_lan_host(lan_host)
+        host = _normalise_lan_host(lan_host) or THIS_MACHINE_ONLY_HOST
         _set_env_value(env_path, FRONTEND_HOST_ENV_KEY, host)
-        if host:
+        if host != THIS_MACHINE_ONLY_HOST:
             print(f"Other computers will reach this installation at http://{host}")
         else:
             print("This installation is reachable from this machine only.")
+    else:
+        host = _fill_in_lan_host(env_path)
+        if host:
+            print(
+                f"Other computers will reach this installation at http://{host}"
+                " (this machine's network address; change it with --lan-host)"
+            )
     write_docker_compose_file(enabled_services=enabled, directory=directory)
 
     from .stack import remember_install_dir

{arcsecond-4.4.1 → arcsecond-4.4.3}/arcsecond/hosting/utils.py

@@ -1,10 +1,24 @@
 import base64
 import os
 import secrets
+import socket
 import subprocess
 from pathlib import Path
 
 
+def lan_ipv4():
+    """This machine's address on the local network, or None.
+
+    No packet is sent: connecting a UDP socket only picks the interface the
+    default route would use, and that is the address to hand around."""
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+            s.connect(("10.255.255.255", 1))
+            return s.getsockname()[0]
+    except OSError:
+        return None
+
+
 def _container_running(name):
     try:
         out = subprocess.run(

{arcsecond-4.4.1 → arcsecond-4.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arcsecond"
-version = "4.4.1"
+version = "4.4.3"
 authors = [
     { name = "Cedric Foellmi", email = "cedric@arcsecond.io" },
 ]

{arcsecond-4.4.1 → arcsecond-4.4.3}/tests/test_hosting_composedoc.py

@@ -58,6 +58,30 @@ def test_optional_services_are_recognised_by_their_markers():
     assert "GCN_CONSUMER_CLIENT_ID" in " ".join(s["alerts"].description)
 
 
+def test_every_service_on_the_backend_image_can_be_given_a_local_build():
+    s = _services()
+    api = [name for name, service in s.items() if "arcsecond-api" in service.image]
+    assert api == ["backend", "worker", "dataworker", "beat", "alerts"]
+    for name in api:
+        assert "ARCSECOND_API_IMAGE" in s[name].env_vars, name
+        assert "ARCSECOND_API_PULL_POLICY" in s[name].env_vars, name
+
+
+def test_the_web_interface_can_be_given_a_local_build():
+    web = _services()["web"]
+    assert (
+        web.image == "ghcr.io/arcsecond-io/arcsecond-web:latest"
+    )  # what an unset key runs
+    assert "ARCSECOND_WEB_IMAGE" in web.env_vars
+    assert "ARCSECOND_WEB_PULL_POLICY" in web.env_vars
+
+
+def test_every_key_the_template_reads_is_documented():
+    for service in composedoc.parse_services(local.packaged_compose_text()):
+        for key in service.env_vars:
+            assert key in composedoc.ENV_KEYS, (service.name, key)
+
+
 def test_every_key_setup_writes_is_documented():
     for key in local.REQUIRED_ENV_PROVIDERS:
         assert key in composedoc.ENV_KEYS, key

{arcsecond-4.4.1 → arcsecond-4.4.3}/tests/test_hosting_local.py

@@ -17,6 +17,9 @@ def _stub_env_generators(monkeypatch):
     monkeypatch.setattr(local, "prompt_shared_data_path", lambda: "/tmp/shared-data")
     monkeypatch.setattr(local, "_offer_token", lambda: None)
     monkeypatch.setattr(local, "_offer_sky_map", lambda env_path, flag: None)
+    # The machine running the tests has a LAN address of its own; tests that
+    # want one give it.
+    monkeypatch.setattr(local, "lan_ipv4", lambda: None)
 
 
 def _packaged_compose_text():
@@ -495,6 +498,72 @@ def test_setup_lan_host_refuses_a_scheme_or_a_path(tmp_path, monkeypatch):
     assert "without scheme" in result.output
 
 
+def _setup_on_lan(tmp_path, monkeypatch, lan, *args):
+    monkeypatch.chdir(tmp_path)
+    _stub_env_generators(monkeypatch)
+    monkeypatch.setattr(local, "_stdin_is_interactive", lambda: False)
+    monkeypatch.setattr(local, "lan_ipv4", lambda: lan)
+    return CliRunner().invoke(local.setup, list(args))
+
+
+def _declared(tmp_path):
+    for line in (tmp_path / ".env").read_text(encoding="utf-8").splitlines():
+        if line.startswith(local.FRONTEND_HOST_ENV_KEY + "="):
+            return line.split("=", 1)[1]
+    return None
+
+
+def test_setup_declares_the_lan_address_when_none_is_declared(tmp_path, monkeypatch):
+    result = _setup_on_lan(tmp_path, monkeypatch, "192.168.1.42")
+    assert result.exit_code == 0, result.output
+    assert _declared(tmp_path) == "192.168.1.42:5555"
+    assert "http://192.168.1.42:5555" in result.output
+    assert "--lan-host" in result.output
+
+
+def test_setup_fills_in_an_empty_address_left_by_an_older_setup(tmp_path, monkeypatch):
+    (tmp_path / ".env").write_text(f"{local.FRONTEND_HOST_ENV_KEY}=\n")
+    result = _setup_on_lan(tmp_path, monkeypatch, "192.168.1.42")
+    assert result.exit_code == 0, result.output
+    assert _declared(tmp_path) == "192.168.1.42:5555"
+
+
+def test_setup_never_overwrites_a_declared_address(tmp_path, monkeypatch):
+    (tmp_path / ".env").write_text(
+        f"{local.FRONTEND_HOST_ENV_KEY}=arcsecond.local:5555\n"
+    )
+    result = _setup_on_lan(tmp_path, monkeypatch, "192.168.1.42")
+    assert result.exit_code == 0, result.output
+    assert _declared(tmp_path) == "arcsecond.local:5555"
+    assert "192.168.1.42" not in result.output
+
+
+def test_setup_lan_host_wins_over_the_detected_address(tmp_path, monkeypatch):
+    result = _setup_on_lan(
+        tmp_path, monkeypatch, "192.168.1.42", "--lan-host", "arcsecond.local"
+    )
+    assert result.exit_code == 0, result.output
+    assert _declared(tmp_path) == "arcsecond.local:5555"
+
+
+def test_setup_leaves_the_address_empty_without_a_network(tmp_path, monkeypatch):
+    for lan in (None, "127.0.0.1"):
+        result = _setup_on_lan(tmp_path, monkeypatch, lan)
+        assert result.exit_code == 0, result.output
+        assert _declared(tmp_path) == ""
+
+
+def test_an_empty_lan_host_keeps_the_links_on_this_machine_across_setups(
+    tmp_path, monkeypatch
+):
+    first = _setup_on_lan(tmp_path, monkeypatch, "192.168.1.42", "--lan-host", "")
+    assert first.exit_code == 0, first.output
+    assert "this machine only" in first.output
+    second = _setup_on_lan(tmp_path, monkeypatch, "192.168.1.42")
+    assert second.exit_code == 0, second.output
+    assert _declared(tmp_path) == local.THIS_MACHINE_ONLY_HOST
+
+
 def test_setup_remembers_the_folder_for_start_to_find(tmp_path, monkeypatch):
     from arcsecond.hosting import stack
 

{arcsecond-4.4.1 → arcsecond-4.4.3}/uv.lock

@@ -155,7 +155,7 @@ wheels = [
 
 [[package]]
 name = "arcsecond"
-version = "4.4.1"
+version = "4.4.3"
 source = { editable = "." }
 dependencies = [
     { name = "alpyca" },