cmdbsyncer 4.3.2__tar.gz → 4.3.4__tar.gz

{cmdbsyncer-4.3.2/cmdbsyncer.egg-info → cmdbsyncer-4.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmdbsyncer
-Version: 4.3.2
+Version: 4.3.4
 Summary: Rule-based modular synchronizer for Checkmk, Netbox, Ansible, I-DOIT, Jira CMDB and 15+ other CMDB/monitoring systems
 Author-email: Kuhn & Ruess GmbH <info@kuhn-ruess.de>
 Maintainer-email: Bastian Kuhn <mail@bastian-kuhn.de>

{cmdbsyncer-4.3.2 → cmdbsyncer-4.3.4}/application/__init__.py

@@ -70,6 +70,13 @@ for _candidate in _config_candidates:
         break
 if os.getcwd() not in sys.path:
     sys.path.insert(0, os.getcwd())
+# A directory named by the operator goes on the path even when it holds no
+# ``local_config.py`` yet: on a container install the first boot is what
+# creates that file, and ``sys self_configure`` has to be able to import it
+# in the same run. An empty directory in front changes nothing otherwise —
+# the import simply falls through to the next entry.
+if _env_dir and _env_dir not in sys.path:
+    sys.path.insert(0, _env_dir)
 
 import importlib
 import pkgutil

{cmdbsyncer-4.3.2 → cmdbsyncer-4.3.4}/application/auth/views.py

@@ -166,8 +166,17 @@ def login():  # pylint: disable=too-many-return-statements,too-many-branches,too
                 if ldap_user:
                     existing_user = ldap_user
                     ldap_authenticated = True
-            except Exception:  # pylint: disable=broad-exception-caught
-                log.log("LDAP login failed", source="AUTH")
+            except Exception as exp:  # pylint: disable=broad-exception-caught
+                # `log.log` already files the traceback, but it sits
+                # collapsed in the detail view of a single entry and reads
+                # like a crash report. The reason belongs in the record
+                # itself, next to the AUTH entries the login handler writes
+                # either side of it, so a list of them tells an unreachable
+                # server apart from a service account with the wrong
+                # password. The person logging in still sees the generic
+                # message; the directory's answer is not theirs to read.
+                log.log("LDAP login failed", source="AUTH",
+                        details=[('email', email), ('error', str(exp))])
                 flash('LDAP Error', 'danger')
                 return render_template('login.html', **context)
 

cmdbsyncer-4.3.4/application/buildinfo.txt

@@ -0,0 +1 @@
+BUILD_DATE=2026-09-16T11:58:47Z

{cmdbsyncer-4.3.2 → cmdbsyncer-4.3.4}/application/changelog/v4.3.md

@@ -1,5 +1,16 @@
 # Version 4.3
 
+## Version 4.3.4
+- FIX: A user the directory created can now log in — a successful directory bind ended in a server error for anybody who has no local password, which is every user created on first login
+- FIX: A directory login that fails records what went wrong, so an unreachable server, a service account with the wrong password and a group mapping naming a role that does not exist can be told apart in Settings → Log
+- FIX: The License page is listed in the Settings menu again, so a license file can be uploaded without having to know the address of the page
+- FIX: The License page names the path it really expects the license file at, instead of a fixed path that was wrong in every container and in most installations made with pip
+
+## Version 4.3.3
+- FEAT: Every release is published as a ready-made container image, so a deployment can pull `ghcr.io/kuhn-ruess/cmdbsyncer:4.3.3` instead of cloning the repository and building it — `docker-compose.registry.yml` is a complete stack that uses it
+- FIX: A container can keep its configuration outside the image by setting CMDBSYNCER_CONFIG_DIR to a mounted directory; without it, replacing the image regenerated the key that the stored account passwords are encrypted with and none of them could be read afterwards
+- FIX: Exporting Checkmk users no longer stops with "pager address may not be null" when a user has no pager address, no mail address or no role; an empty field is sent as empty instead of as nothing, which also stops such a user from being rewritten on every export
+
 ## Version 4.3.2
 - FEAT: The "create missing hosts" card of the Checkmk data quality check has a lowercase toggle, so host names the uppercase check reported can be put into the syncer in lowercase — the appended domain included
 - FIX: A cronjob whose account is gone — for example after importing rules without the matching accounts — no longer breaks the Cronjob page; the group is listed with a note and can be opened to assign the right account

{cmdbsyncer-4.3.2 → cmdbsyncer-4.3.4}/application/enterprise.py

@@ -5,11 +5,19 @@ Populated by `load_package()` from the optional `cmdbsyncer_enterprise` package.
 If the package is not installed (or its license check fails), the registry
 stays empty and all hooks become no-ops — OSS code continues to work.
 
+The published Docker image ships the package on every install, licensed or
+not, so a customer who buys a license only has to drop in `license.jwt`.
+An install without one must therefore look exactly like an install without
+the package: `load_package()` stays silent when there is no license to
+activate, and only reports when a license is there and something went wrong
+with it.
+
 `load_package()` must be called explicitly from the app factory *after* the
 MongoEngine `db` handle has been created, because the enterprise package
 transitively imports `application.models.*`, which depend on
 `from application import db`.
 """
+import os
 import sys
 import importlib.util
 
@@ -30,7 +38,6 @@ def _report(message):
     """
     # ``./cmdbsyncer <command>`` sets CMDBSYNCER_CLI so command output isn't
     # preceded by a banner line — the web/worker processes keep the banner.
-    import os  # pylint: disable=import-outside-toplevel
     if os.environ.get("CMDBSYNCER_CLI") == "1":
         return
     global _pending_report  # pylint: disable=global-statement
@@ -56,6 +63,34 @@ def emit_load_status(logger=None):
         print(f"[cmdbsyncer-enterprise] {message}", file=sys.stderr, flush=True)
 
 
+def license_path():
+    """Return the file the enterprise package reads its license from.
+
+    Mirrors the resolution in ``cmdbsyncer_enterprise.license``: the
+    ``CMDBSYNCER_LICENSE`` environment variable wins, otherwise
+    ``license.jwt`` next to the deployment's ``local_config.py``. Resolved
+    here instead of asked of the package, because the question comes up
+    exactly when the package cannot be imported. Returns None when neither
+    candidate can be determined.
+    """
+    env_path = os.environ.get('CMDBSYNCER_LICENSE')
+    if env_path:
+        return env_path
+    try:
+        spec = importlib.util.find_spec('local_config')
+    except (ImportError, ValueError):
+        spec = None
+    if spec and spec.origin:
+        return os.path.join(os.path.dirname(spec.origin), 'license.jwt')
+    return None
+
+
+def license_file_present():
+    """True when a license file exists where the package looks for it."""
+    path = license_path()
+    return bool(path) and os.path.isfile(path)
+
+
 def register_feature(name, hook_fn=None):
     """Enable a named feature and optionally bind an implementation function."""
     _features.add(name)
@@ -86,6 +121,13 @@ def load_package():
         load_status = 'active'
         _report("package loaded successfully")
     except Exception as exp:  # pylint: disable=broad-exception-caught
+        if not license_file_present():
+            # Nothing is wrong here — this install simply has no license,
+            # which is the normal state for every Community Edition user of
+            # the Docker image. Reporting it would put a line that reads
+            # like a failure in front of every start they ever do.
+            load_status = 'inactive: no license installed'
+            return
         load_status = f'failed: {exp}'
         _report(
             f"package installed but failed to activate "

{cmdbsyncer-4.3.2 → cmdbsyncer-4.3.4}/application/models/user.py

@@ -159,8 +159,17 @@ class User(db.Document, UserMixin):
 
     def check_password(self, password):
         """
-        Password checker
+        Password checker.
+
+        A user who only ever authenticated against a directory has no local
+        hash at all. The login view asks every user for one before it decides
+        — it has to, a directory answer of "no" must still allow a local
+        password — so without this guard that question reached werkzeug with
+        None and raised, turning a successful LDAP bind into a server error.
+        No hash simply means no local password, which never matches.
         """
+        if not self.pwdhash:
+            return False
         return check_password_hash(self.pwdhash, password)
 
     def account_scope(self):

{cmdbsyncer-4.3.2 → cmdbsyncer-4.3.4}/application/plugins/checkmk/tests/test_cmk_rules.py

@@ -351,7 +351,7 @@ class TestCheckmkRuleSync(unittest.TestCase):
             'loop_over_list': False,
             'list_to_loop': '',
             'condition_label_template': '',
-            'condition_host': 'fmg-host01',
+            'condition_host': 'host01',
             'condition_service': '',
             'condition_service_label': '',
         }
@@ -359,7 +359,7 @@ class TestCheckmkRuleSync(unittest.TestCase):
         # Owner host: HOSTNAME == condition_host → optimize path.
         self.sync.calculate_rules_of_host(
             {'agent_config:mrpe': [dict(outcome)]},
-            {'all': {'HOSTNAME': 'fmg-host01'}})
+            {'all': {'HOSTNAME': 'host01'}})
         # Foreign host: HOSTNAME != condition_host → plain variant.
         self.sync.calculate_rules_of_host(
             {'agent_config:mrpe': [dict(outcome)]},
@@ -370,7 +370,7 @@ class TestCheckmkRuleSync(unittest.TestCase):
         rules = self.sync.rulsets_by_type['agent_config:mrpe']
         self.assertEqual(len(rules), 1)
         self.assertEqual(
-            rules[0]['condition']['host_name']['match_on'], ['fmg-host01'])
+            rules[0]['condition']['host_name']['match_on'], ['host01'])
 
     def test_collect_rule_dedupes_without_rescanning(self):
         # Every host feeds the same list, so the duplicate check used to
@@ -420,7 +420,7 @@ class TestCheckmkRuleSync(unittest.TestCase):
                 'loop_over_list': False,
                 'list_to_loop': '',
                 'condition_label_template': '',
-                'condition_host': 'fmg-host01',
+                'condition_host': 'host01',
                 'condition_service': '',
                 'condition_service_label': '',
             })

{cmdbsyncer-4.3.2 → cmdbsyncer-4.3.4}/application/plugins/checkmk/tests/test_inventorize.py

@@ -144,7 +144,7 @@ class TestInventorizeHosts(unittest.TestCase):
                 'extensions': {
                     'effective_attributes': None,
                     'labels': {
-                        'piggyback_source_vc-prd-w-mgmt.services.p.rz.drv': 'yes',
+                        'piggyback_source_srv01.mgmt.dc1.example.com': 'yes',
                         'plain_label': 'value',
                     },
                 },
@@ -156,9 +156,9 @@ class TestInventorizeHosts(unittest.TestCase):
             self.inv.get_attr_labels()
 
         inv = self.inv.config_inventory['host1']
-        self.assertIn('label_piggyback_source_vc-prd-w-mgmt_services_p_rz_drv', inv)
+        self.assertIn('label_piggyback_source_srv01_mgmt_dc1_example_com', inv)
         self.assertNotIn(
-            'label_piggyback_source_vc-prd-w-mgmt.services.p.rz.drv', inv,
+            'label_piggyback_source_srv01.mgmt.dc1.example.com', inv,
         )
         self.assertIn('label_plain_label', inv)
 

{cmdbsyncer-4.3.2 → cmdbsyncer-4.3.4}/application/plugins/checkmk/tests/test_users.py

@@ -44,6 +44,53 @@ class TestCheckmkUserSync(unittest.TestCase):
             setattr(user, key, val)
         return user
 
+    @patch('application.plugins.checkmk.users.CheckmkUserMngmt')
+    @patch('builtins.print')
+    def test_a_never_filled_field_is_sent_empty_not_null(self, mock_print,
+                                                         mock_mngmt):
+        # Checkmk answers "pager address may not be null" for every one of
+        # these, and a field nobody ever filled in is None on the document
+        user = self._make_user(pager_address=None, email=None,
+                               disable_login=None, roles=None,
+                               contact_groups=None, full_name=None)
+        mock_mngmt.objects.return_value = [user]
+
+        with patch.object(self.sync, 'request') as mock_req:
+            mock_req.side_effect = [({}, {'status_code': 404}),
+                                    ({'id': 'testuser'}, {})]
+            self.sync.export_users()
+
+        sent = mock_req.call_args_list[1][1]['data']
+        self.assertEqual(sent['pager_address'], '')
+        self.assertEqual(sent['contact_options']['email'], '')
+        self.assertEqual(sent['disable_login'], False)
+        self.assertEqual(sent['roles'], [])
+        self.assertEqual(sent['contactgroups'], [])
+        # A user without a full name is still a user Checkmk accepts
+        self.assertEqual(sent['fullname'], 'testuser')
+
+    @patch('application.plugins.checkmk.users.CheckmkUserMngmt')
+    @patch('builtins.print')
+    def test_an_empty_field_is_not_a_change(self, mock_print, mock_mngmt):
+        # Checkmk answers with the empty value, so a None on our side used
+        # to look different on every run and rewrote the user each time
+        user = self._make_user(pager_address=None, email=None)
+        mock_mngmt.objects.return_value = [user]
+        cmk_side = {
+            'fullname': 'Test User', 'disable_login': False,
+            'pager_address': '', 'contactgroups': ['all'],
+            'roles': ['user'], 'contact_options': {'email': ''},
+        }
+
+        with patch.object(self.sync, 'request') as mock_req:
+            mock_req.side_effect = [
+                ({'extensions': cmk_side}, {'ETag': 'x'}),
+            ]
+            self.sync.export_users()
+
+        # Only the GET happened, nothing was written back
+        self.assertEqual(mock_req.call_count, 1)
+
     @patch('application.plugins.checkmk.users.CheckmkUserMngmt')
     @patch('builtins.print')
     def test_export_users_creates_new(self, mock_print, mock_mngmt):

{cmdbsyncer-4.3.2 → cmdbsyncer-4.3.4}/application/plugins/checkmk/users.py

@@ -31,26 +31,31 @@ class CheckmkUserSync(CMK2):
             url = f"/objects/user_config/{user.user_id}"
             cmk_user = self.request(url, method="GET")
             # ({}, {'status_code': 404})
+            # A field never filled in is None on the document, and the
+            # Checkmk API rejects null for every one of these ("pager
+            # address may not be null"). Checkmk itself answers with the
+            # empty value, so sending that is also what keeps has_changes
+            # from reporting a difference on every single run.
             user_template = {
               "username": user.user_id,
-              "fullname": user.full_name,
+              "fullname": user.full_name or user.user_id,
               "auth_option": {
                 "auth_type": "password",
                 "password": user.password
               },
-              "disable_login": user.disable_login,
+              "disable_login": bool(user.disable_login),
               "contact_options": {
-                "email": user.email
+                "email": user.email or ''
               },
-              "pager_address": user.pager_address,
+              "pager_address": user.pager_address or '',
               "idle_timeout": {
                 "option": "global"
               },
-              "roles": user.roles,
+              "roles": list(user.roles or []),
               #"authorized_sites": [
               #  "heute"
               #],
-              "contactgroups": user.contact_groups,
+              "contactgroups": list(user.contact_groups or []),
               "disable_notifications": {
                 "disable": False
               },

{cmdbsyncer-4.3.2 → cmdbsyncer-4.3.4}/application/plugins/maintenance/__init__.py

@@ -3,6 +3,7 @@
 Maintenance Module
 """
 import os
+import importlib
 import datetime
 import shutil
 import string
@@ -759,19 +760,43 @@ def migrate_accounts(old_key, new_key):
             account.set_password(password, new_key)
 
 
+def _local_config_path():
+    """Where this deployment keeps its local_config.py.
+
+    ``$CMDBSYNCER_CONFIG_DIR`` first, matching the search order the app
+    factory uses to import it, then the working directory as before. The
+    distinction matters for container installs: the working directory is a
+    layer of the image and is replaced on every upgrade, so a SECRET_KEY and
+    CRYPTOGRAPHY_KEY written there are regenerated with the next pull —
+    which leaves every stored account password undecryptable. Pointing the
+    variable at a mounted directory keeps them.
+    """
+    config_dir = os.environ.get('CMDBSYNCER_CONFIG_DIR')
+    if config_dir:
+        os.makedirs(config_dir, exist_ok=True)
+        return os.path.join(config_dir, 'local_config.py')
+    return 'local_config.py'
+
+
 def _ensure_local_config():
     """Create a stub local_config.py if missing."""
     print("Check for local_config.py File")
-    if os.path.isfile('local_config.py'):
+    path = _local_config_path()
+    if os.path.isfile(path):
         print(" -> Existed")
         return
-    with open('local_config.py', 'w', encoding="utf-8") as lf:
+    with open(path, 'w', encoding="utf-8") as lf:
         lf.write("#!/usr/bin/env python3\n")
         lf.write('"""\nLocal Config File\n"""\n')
         lf.write("import logging\n")
         lf.write("# Only Update from here inside the config = {} object\n")
         lf.write("config = {}\n")
-    print(" -> Created new local_config.py")
+    # The directory may have been put on sys.path while it was still empty
+    # (a fresh mounted config volume), in which case the import system has
+    # cached it as holding nothing. The `from local_config import config`
+    # further down runs in this same process.
+    importlib.invalidate_caches()
+    print(f" -> Created new local_config.py at {path}")
 
 
 def _ensure_plugins_dir():
@@ -891,13 +916,22 @@ def self_configure():
         migrate_accounts(old_key, new_key)
 
         config['CRYPTOGRAPHY_KEY'] = new_key
-    with open('local_config.py', 'w', encoding="utf-8") as lf:
+    with open(_local_config_path(), 'w', encoding="utf-8") as lf:
         lf.write("#!/usr/bin/env python3\n")
         lf.write('"""\nLocal Config File\n"""\n')
         lf.write("import logging\n")
         lf.write("# Only Update from here inside the config = {} object\n")
         lf.write(f"config = {pformat(config)}\n")
 
+    # What was just written has to reach the running process as well. On a
+    # fresh install the app factory found no local_config.py to import, so
+    # app.config still carries BaseConfig's defaults — CRYPTOGRAPHY_KEY
+    # among them, as None. The migrations below this line read from
+    # app.config, as does anything an operator runs in the same call, and a
+    # key of None fails them with "no CRYPTOGRAPHY_KEY configured" while the
+    # file on disk has had one all along.
+    app.config.update(config)
+
     # Migrate Users
     print("Migrate users")
     User.migrate_missing_names()

{cmdbsyncer-4.3.2 → cmdbsyncer-4.3.4}/application/templates/license_info.html

@@ -93,7 +93,8 @@
         <div class="alert alert-warning mb-0" role="alert">
           <h4 class="alert-heading">Enterprise package installed, but license not active</h4>
           <p class="mb-2">
-            Default license path: <code>/opt/cmdbsyncer/license.jwt</code>
+            Expected license path:
+            <code>{{ license_destination or 'cannot be resolved on this install' }}</code>
             (override via <code>CMDBSYNCER_LICENSE</code>).
           </p>
           {% if load_status %}

{cmdbsyncer-4.3.2 → cmdbsyncer-4.3.4}/application/views/license.py

@@ -2,7 +2,6 @@
 License Information View
 """
 import importlib.util
-import os
 from datetime import datetime
 from pathlib import Path
 
@@ -21,13 +20,7 @@ _MAX_LICENSE_BYTES = 16 * 1024
 
 def _resolve_destination():
     """Pick the same destination the enterprise loader reads from."""
-    env_path = os.environ.get('CMDBSYNCER_LICENSE')
-    if env_path:
-        return env_path
-    spec = importlib.util.find_spec('local_config')
-    if spec and spec.origin:
-        return str(Path(spec.origin).parent / 'license.jwt')
-    return None
+    return enterprise.license_path()
 
 
 def _enterprise_pubkey_path():
@@ -83,10 +76,13 @@ class LicenseView(BaseView):
         return current_user.is_authenticated and current_user.global_admin
 
     def is_visible(self):
-        # Community Edition installs (no enterprise package on disk) have
-        # nothing useful on the License page — no upload form, no feature
-        # table — so hide the menu entry to avoid pointing admins at a
-        # dead end. The route stays reachable via direct URL for support.
+        # Shown whenever the package is on disk — which, with the Docker
+        # image, is everywhere. That is deliberate: the page is where a
+        # license gets uploaded, so hiding it until a license exists leaves
+        # a customer who just bought one with nowhere to go. It is not a
+        # dead end for a Community Edition install either; it names the
+        # destination path, reports why nothing is active, and carries the
+        # upload form. `is_accessible` keeps all of it to global admins.
         return importlib.util.find_spec('cmdbsyncer_enterprise') is not None
 
     @expose('/')

{cmdbsyncer-4.3.2 → cmdbsyncer-4.3.4/cmdbsyncer.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmdbsyncer
-Version: 4.3.2
+Version: 4.3.4
 Summary: Rule-based modular synchronizer for Checkmk, Netbox, Ansible, I-DOIT, Jira CMDB and 15+ other CMDB/monitoring systems
 Author-email: Kuhn & Ruess GmbH <info@kuhn-ruess.de>
 Maintainer-email: Bastian Kuhn <mail@bastian-kuhn.de>

{cmdbsyncer-4.3.2 → cmdbsyncer-4.3.4}/cmdbsyncer.egg-info/SOURCES.txt

@@ -408,11 +408,13 @@ syncerapi/v1/rest/__init__.py
 tests/test_account_macro.py
 tests/test_api.py
 tests/test_api_csrf_invariant.py
+tests/test_config_dir.py
 tests/test_cron_missing_account.py
 tests/test_csrf_config.py
 tests/test_data_quality_duplicates.py
 tests/test_default_view.py
 tests/test_disabled_row_style.py
+tests/test_enterprise_quiet.py
 tests/test_folder_builder_js.py
 tests/test_global_account_presets.py
 tests/test_host_cleanup.py
@@ -440,5 +442,8 @@ tests/test_search_parser.py
 tests/test_security_fixes.py
 tests/test_stale_indexes.py
 tests/test_template_merge_fields.py
+tests/test_user_scope_smoke.py
 tests/test_view_permission_flags.py
+tests/test_web_boot_smoke.py
+tests/test_web_requests_smoke.py
 tests/test_webhook_token_hash.py

{cmdbsyncer-4.3.2 → cmdbsyncer-4.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cmdbsyncer"
-version = "4.3.2"
+version = "4.3.4"
 description = "Rule-based modular synchronizer for Checkmk, Netbox, Ansible, I-DOIT, Jira CMDB and 15+ other CMDB/monitoring systems"
 readme = "README.md"
 license = { text = "MIT" }

cmdbsyncer-4.3.4/tests/test_config_dir.py

@@ -0,0 +1,112 @@
+"""
+A container replaces /srv with every update, so a deployment that wants to
+keep its SECRET_KEY and CRYPTOGRAPHY_KEY points CMDBSYNCER_CONFIG_DIR at a
+mounted directory instead. Three things have to hold for that to work, and
+all of them are invisible until the day somebody upgrades:
+
+* the directory is on the import path even while it is still empty — the
+  first boot is what creates local_config.py in it, and `sys self_configure`
+  has to be able to import the file it just wrote, in that same run
+* `sys self_configure` writes to that directory rather than to the working
+  directory it happens to be started from
+* the license file is looked for next to it, so an uploaded license survives
+  the upgrade as well
+
+The real import order only exists in a fresh interpreter, so these run in a
+subprocess. The working directory is deliberately a *different* scratch
+directory than the config directory — with the two pointing at the same
+place, a path that quietly fell back to the working directory would pass.
+"""
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+
+_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def _run(snippet, seed_local_config=None):
+    """Run `snippet` with CMDBSYNCER_CONFIG_DIR set, from an unrelated cwd.
+
+    `seed_local_config` is written into the config directory beforehand;
+    without it the directory stays empty, which is the first-boot state.
+    `{config_dir}` is substituted in the snippet.
+    """
+    with tempfile.TemporaryDirectory() as config_dir, \
+            tempfile.TemporaryDirectory() as workdir:
+        if seed_local_config is not None:
+            with open(os.path.join(config_dir, 'local_config.py'),
+                      'w', encoding='utf-8') as fh:
+                fh.write(seed_local_config)
+        env = dict(os.environ)
+        env['PYTHONPATH'] = _REPO_ROOT
+        # CLI mode keeps the import light — no Flask-Admin scaffolding, and
+        # therefore no live MongoDB needed.
+        env['CMDBSYNCER_CLI'] = '1'
+        env['CMDBSYNCER_CONFIG_DIR'] = config_dir
+        env['config'] = 'base'
+        env.pop('CMDBSYNCER_LICENSE', None)
+        return subprocess.run(
+            [sys.executable, '-c', snippet.replace('{config_dir}', config_dir)],
+            cwd=workdir, env=env, capture_output=True, text=True, check=False,
+        )
+
+
+class TestEmptyConfigDirIsImportable(unittest.TestCase):
+    """The first boot happens before local_config.py exists anywhere."""
+
+    def test_directory_is_on_the_path(self):
+        """An empty config directory is still an import location."""
+        result = _run(
+            "import sys\n"
+            "import application\n"
+            "print('ON_PATH', '{config_dir}' in sys.path)\n"
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn('ON_PATH True', result.stdout)
+
+
+class TestConfigDirWins(unittest.TestCase):
+    """Config belongs in the mounted directory, not in the image layer."""
+
+    def test_self_configure_writes_to_the_config_dir(self):
+        """The generated keys land in the mounted directory."""
+        result = _run(
+            "import os\n"
+            "from application.plugins.maintenance import _local_config_path\n"
+            "expected = os.path.join(os.environ['CMDBSYNCER_CONFIG_DIR'],\n"
+            "                        'local_config.py')\n"
+            "print('MATCHES', _local_config_path() == expected)\n"
+            "print('NOT_CWD', _local_config_path() != 'local_config.py')\n",
+            seed_local_config="config = {}\n",
+        )
+        self.assertIn('NOT_CWD True', result.stdout)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn('MATCHES True', result.stdout)
+
+    def test_the_settings_are_read_from_there(self):
+        """And the app reads its configuration back from the same place."""
+        result = _run(
+            "from application import app\n"
+            "print('MARKER', app.config['MARKER'])\n",
+            seed_local_config="config = {'MARKER': 'from-the-config-dir'}\n",
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn('MARKER from-the-config-dir', result.stdout)
+
+    def test_the_license_is_looked_for_next_to_it(self):
+        """An uploaded license survives the upgrade along with it."""
+        result = _run(
+            "from application import enterprise\n"
+            "print('LICENSE', enterprise.license_path())\n",
+            seed_local_config="config = {}\n",
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        license_path = result.stdout.split('LICENSE ')[1].strip()
+        self.assertTrue(license_path.endswith('/license.jwt'), license_path)
+        self.assertNotEqual(os.path.dirname(license_path), os.getcwd())
+
+
+if __name__ == '__main__':
+    unittest.main()