Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

fix(api): honest errors for the installer routes, and the right agent repo

Juan Denis3909c34706c8
diff --git a/backend/app/api/servers.py b/backend/app/api/servers.py
index 85fd2d1e..48a81904 100644
--- a/backend/app/api/servers.py
+++ b/backend/app/api/servers.py
@@ -5,6 +5,7 @@ Endpoints for managing remote servers and their agents.
"""
import os
+import re
import hashlib
import hmac
import requests
@@ -1856,12 +1857,67 @@ def list_terminal_sessions():
# ==================== Installation Scripts ====================
def _get_scripts_dir():
- """Get the scripts directory path"""
+ """Resolve the directory holding the fleet-agent installer scripts.
+
+ Every shipped layout has to land on a real directory here:
+
+ * git checkout / release tarball -> ``<tree root>/scripts``
+ * Docker image -> ``/app/scripts``, which exists only
+ because the Dockerfile explicitly copies the two installers there.
+
+ ``SERVERKIT_SCRIPTS_DIR`` overrides the guess for layouts that split the
+ backend away from the rest of the tree.
+ """
+ override = os.environ.get('SERVERKIT_SCRIPTS_DIR')
+ if override:
+ return override
# Go up from backend/app/api to backend, then to scripts
base_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(__file__))))
return os.path.join(base_dir, 'scripts')
+def _load_installer(filename):
+ """Read an agent installer off disk and stamp this panel's coordinates in.
+
+ Returns ``(content, None)`` on success or ``(None, error_response)`` when the
+ file is absent, so the two endpoints below cannot drift apart.
+ """
+ script_path = os.path.join(_get_scripts_dir(), filename)
+
+ if not os.path.exists(script_path):
+ # A missing installer is a packaging fault on THIS panel, never a bad
+ # request. The old 404 asserted "no such URL", which is exactly what sent
+ # issue #101's reporter hunting for a wrong path -- they filed it as
+ # "incorrect paths in setup" -- when the file had simply never been
+ # shipped into the image. 503 says "this server is broken, not your URL",
+ # and the log line names the path actually searched so an operator can
+ # confirm it in one look instead of guessing.
+ current_app.logger.error(
+ 'Agent installer %s is missing from this deployment (searched %s). '
+ 'Fleet enrollment via /api/v1/servers/%s cannot work until it is '
+ 'restored; see docs/ARCHITECTURE.md.',
+ filename, script_path, filename
+ )
+ return None, (jsonify({
+ 'error': f'{filename} is not present on this ServerKit panel',
+ 'detail': (
+ 'The panel serves this installer from its own filesystem and the '
+ 'file is missing, so this is a packaging/deployment problem with '
+ 'this panel rather than a wrong URL. The panel log records the '
+ 'exact path searched.'
+ ),
+ 'searched_path': script_path,
+ }), 503)
+
+ with open(script_path, 'r', encoding='utf-8') as f:
+ content = f.read()
+
+ # Replace placeholders with actual values
+ content = content.replace('https://your-serverkit.com', _get_external_base_url())
+ content = content.replace('jhd3197/serverkit-agent', AGENT_GITHUB_REPO)
+ return content, None
+
+
@servers_bp.route('/install.sh', methods=['GET'])
def get_install_script_linux():
"""
@@ -1870,22 +1926,16 @@ def get_install_script_linux():
This endpoint serves the bash installation script for installing
the ServerKit agent on Linux systems.
- Usage:
- curl -fsSL https://your-server/api/v1/servers/install.sh | sudo bash -s -- \\
+ Usage (download-then-run, not `curl | bash`: a pipeline reports bash's exit
+ status, so a failed download would exit 0 having installed nothing):
+ curl -fsSL https://your-server/api/v1/servers/install.sh \\
+ -o /tmp/serverkit-agent-install.sh \\
+ && sudo bash /tmp/serverkit-agent-install.sh \\
--token "YOUR_TOKEN" --server "https://your-server"
"""
- script_path = os.path.join(_get_scripts_dir(), 'install.sh')
-
- if not os.path.exists(script_path):
- return jsonify({'error': 'Installation script not found'}), 404
-
- with open(script_path, 'r', encoding='utf-8') as f:
- content = f.read()
-
- # Replace placeholders with actual values
- server_url = _get_external_base_url()
- content = content.replace('https://your-serverkit.com', server_url)
- content = content.replace('jhd3197/ServerKit', GITHUB_REPO)
+ content, error = _load_installer('install.sh')
+ if error is not None:
+ return error
# Inject the agent version the panel already resolved so enrollment does
# not depend on the installer rediscovering it via the GitHub API. Best
@@ -1922,18 +1972,9 @@ def get_install_script_windows():
irm https://your-server/api/v1/servers/install.ps1 | iex; \\
Install-ServerKitAgent -Token "YOUR_TOKEN" -Server "https://your-server"
"""
- script_path = os.path.join(_get_scripts_dir(), 'install.ps1')
-
- if not os.path.exists(script_path):
- return jsonify({'error': 'Installation script not found'}), 404
-
- with open(script_path, 'r', encoding='utf-8') as f:
- content = f.read()
-
- # Replace placeholders with actual values
- server_url = _get_external_base_url()
- content = content.replace('https://your-serverkit.com', server_url)
- content = content.replace('jhd3197/ServerKit', GITHUB_REPO)
+ content, error = _load_installer('install.ps1')
+ if error is not None:
+ return error
return Response(
content,
@@ -1977,7 +2018,14 @@ def get_install_instructions(server_id):
return jsonify({
'linux': {
- 'one_liner': f'curl -fsSL {api_url}/install.sh | sudo bash -s -- --token "YOUR_TOKEN" --server "{base_url}"',
+ # Download-then-run rather than `curl … | sudo bash`: in a pipeline
+ # the shell reports bash's exit status, so a failed download exits 0
+ # and installs nothing without saying so (issue #101).
+ 'one_liner': (
+ f'curl -fsSL {api_url}/install.sh -o /tmp/serverkit-agent-install.sh '
+ f'&& sudo bash /tmp/serverkit-agent-install.sh '
+ f'--token "YOUR_TOKEN" --server "{base_url}"'
+ ),
'manual': [
f'# Download the script',
f'curl -fsSL {api_url}/install.sh -o install.sh',
@@ -2009,7 +2057,18 @@ _releases_cache = {
'expires': None
}
-GITHUB_REPO = os.environ.get('SERVERKIT_GITHUB_REPO', 'jhd3197/ServerKit')
+# The agent is built and released from its own repo, tagged plain `vX.Y.Z`. It
+# used to ship from this monorepo under `agent-v*` tags; when it moved out,
+# nothing here followed it, so this lookup searched a repo that has no agent
+# releases at all -- /agent/version answered 503 for every agent polling for an
+# update, and the served installer downloaded from a 404. Point both at the
+# repo that actually publishes the binaries.
+AGENT_GITHUB_REPO = os.environ.get('SERVERKIT_AGENT_GITHUB_REPO', 'jhd3197/serverkit-agent')
+
+# Matches vX.Y.Z but not the malformed release tagged just "v" that sits in the
+# agent repo's release list -- that one parses to an empty version and builds
+# download URLs like .../releases/download/v/serverkit-agent--linux-amd64.tar.gz.
+_AGENT_TAG_RE = re.compile(r'^v(\d[^\s]*)$')
def _get_latest_agent_release():
@@ -2021,11 +2080,10 @@ def _get_latest_agent_release():
return _releases_cache['data']
try:
- # Fetch releases from GitHub. per_page=100: agent-v* tags share this
- # repo with panel releases, which can push them off the default
- # 30-entry first page.
+ # Every release in the agent repo is an agent release, but ask for 100
+ # anyway so a run of pre-release tags cannot hide the newest stable one.
response = requests.get(
- f'https://api.github.com/repos/{GITHUB_REPO}/releases',
+ f'https://api.github.com/repos/{AGENT_GITHUB_REPO}/releases',
headers={'Accept': 'application/vnd.github.v3+json'},
params={'per_page': 100},
timeout=10
@@ -2035,8 +2093,9 @@ def _get_latest_agent_release():
# Find latest agent release
for release in releases:
- if release.get('tag_name', '').startswith('agent-v'):
- version = release['tag_name'].replace('agent-v', '')
+ match = _AGENT_TAG_RE.match(release.get('tag_name', ''))
+ if match:
+ version = match.group(1)
# Build assets map
assets = {}
diff --git a/backend/tests/test_agent_installer_endpoints.py b/backend/tests/test_agent_installer_endpoints.py
new file mode 100644
index 00000000..6aedebf9
--- /dev/null
+++ b/backend/tests/test_agent_installer_endpoints.py
@@ -0,0 +1,278 @@
+"""Tests for the unauthenticated fleet-agent installer endpoints.
+
+Regression cover for issue #101: ``GET /api/v1/servers/install.sh`` answered 404
+on every Docker deployment because the Dockerfile never copied ``scripts/`` into
+the image. Nothing caught it, and no ordinary endpoint test could have: pytest
+runs from the source tree, where ``scripts/install.sh`` is always present. The
+bug lived in the *packaging*, not the code.
+
+So this file tests both halves:
+
+1. the endpoints behave (they serve a script, unauthenticated, and fail loudly
+ with a server-error status when the file is absent), and
+2. the packaging invariant -- every installer the panel serves off disk is
+ actually copied into the image by the Dockerfile.
+
+Test (2) is the one that would have caught #101.
+"""
+
+import os
+import re
+from unittest.mock import patch
+
+import pytest
+
+from app.api import servers as servers_api
+from app.api.servers import _get_scripts_dir
+
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+# The installers the panel serves over HTTP, and the route each is served from.
+SERVED_INSTALLERS = [
+ ('install.sh', '/api/v1/servers/install.sh'),
+ ('install.ps1', '/api/v1/servers/install.ps1'),
+]
+
+
+# ---------------------------------------------------------------- endpoints
+
+
[email protected]('filename,route', SERVED_INSTALLERS)
+def test_installer_is_served_without_auth(client, filename, route):
+ """Enrollment happens on a box that has no panel credentials yet.
+
+ The one-liner is ``curl ... | sudo bash`` run on a brand new server, so these
+ two routes must stay reachable anonymously.
+ """
+ response = client.get(route)
+
+ assert response.status_code == 200, (
+ f'{route} returned {response.status_code}; the panel prints this URL in '
+ f'its own Add Server dialog, so a non-200 means fleet enrollment is dead'
+ )
+ assert len(response.get_data(as_text=True)) > 0
+
+
+def test_install_sh_serves_the_real_script(client):
+ body = client.get('/api/v1/servers/install.sh').get_data(as_text=True)
+
+ assert body.startswith('#!/bin/bash')
+ # Placeholder substitution ran: the shipped file says your-serverkit.com,
+ # the served copy must point at this panel instead.
+ assert 'https://your-serverkit.com' not in body
+ assert '--token' in body
+
+
+def test_install_ps1_serves_the_real_script(client):
+ body = client.get('/api/v1/servers/install.ps1').get_data(as_text=True)
+
+ assert 'Install-ServerKitAgent' in body
+ assert 'https://your-serverkit.com' not in body
+
+
+def test_missing_installer_is_a_server_error_not_a_404(client, monkeypatch):
+ """A missing installer is this panel's fault, and must not read as a bad URL.
+
+ #101 was reported as "incorrect paths in setup" because the panel answered
+ 404 -- the reporter reasonably concluded they had the wrong URL, when in fact
+ the server was missing a file it was supposed to ship. 5xx moves the blame to
+ where it belongs and stops the next person re-filing the same wrong diagnosis.
+ """
+ monkeypatch.setenv('SERVERKIT_SCRIPTS_DIR', os.path.join(REPO_ROOT, 'no-such-dir'))
+
+ for _filename, route in SERVED_INSTALLERS:
+ response = client.get(route)
+
+ assert response.status_code >= 500, (
+ f'{route} answered {response.status_code} for a missing file; 4xx '
+ f'blames the caller for a server-side packaging fault'
+ )
+ payload = response.get_json()
+ # The operator needs the path that was actually searched, not a bare
+ # "not found" -- that is the single fact that makes this diagnosable.
+ assert 'searched_path' in payload
+ assert 'no-such-dir' in payload['searched_path']
+
+
+def test_scripts_dir_env_override_is_honoured(tmp_path, monkeypatch):
+ monkeypatch.setenv('SERVERKIT_SCRIPTS_DIR', str(tmp_path))
+ assert _get_scripts_dir() == str(tmp_path)
+
+
+# ---------------------------------------------------------------- packaging
+
+
+def _dockerfile_copied_paths():
+ """Every source path the root Dockerfile COPYs out of the build context."""
+ with open(os.path.join(REPO_ROOT, 'Dockerfile'), 'r', encoding='utf-8') as f:
+ dockerfile = f.read()
+
+ # Join line continuations so a wrapped COPY is still one instruction.
+ dockerfile = re.sub(r'\\\s*\n', ' ', dockerfile)
+
+ copied = set()
+ for line in dockerfile.splitlines():
+ line = line.strip()
+ if not line.upper().startswith('COPY '):
+ continue
+ args = [a for a in line.split()[1:] if not a.startswith('--')]
+ if len(args) < 2:
+ continue
+ # Last arg is the destination; everything before it is a source. Sources
+ # on a `COPY --from=<stage>` come from another stage, not the repo.
+ if '--from=' in line:
+ continue
+ copied.update(args[:-1])
+ return copied
+
+
[email protected]('filename,_route', SERVED_INSTALLERS)
+def test_dockerfile_ships_every_installer_the_panel_serves(filename, _route):
+ """The invariant that #101 violated.
+
+ The panel reads these files from its own filesystem at request time. If the
+ Dockerfile does not copy them, the endpoints 404 in every container while
+ passing every test in this suite -- because pytest runs against the source
+ tree, where the files always exist. Assert the packaging directly.
+ """
+ copied = _dockerfile_copied_paths()
+
+ assert f'scripts/{filename}' in copied, (
+ f'scripts/{filename} is served by the panel at request time but the '
+ f'Dockerfile never copies it into the image, so the endpoint will 404 in '
+ f'every Docker deployment. Dockerfile COPY sources found: {sorted(copied)}'
+ )
+
+
[email protected]('filename,_route', SERVED_INSTALLERS)
+def test_installer_exists_where_the_panel_looks_for_it(filename, _route):
+ """Source-tree layout check: the resolver must point at the real files."""
+ path = os.path.join(_get_scripts_dir(), filename)
+ assert os.path.isfile(path), f'{filename} not found at resolved path {path}'
+
+
+def test_served_installers_are_self_contained(filename='install.sh'):
+ """They must not source scripts/lib -- the image ships only these two files.
+
+ If an installer ever grows a `source scripts/lib/...`, shipping just the two
+ files stops being sufficient and the Dockerfile has to copy more.
+ """
+ path = os.path.join(_get_scripts_dir(), filename)
+ with open(path, 'r', encoding='utf-8') as f:
+ body = f.read()
+
+ assert not re.search(r'^\s*(source|\.)\s+\S*scripts/lib', body, re.MULTILINE), (
+ 'install.sh now depends on scripts/lib; the Dockerfile copies only '
+ 'scripts/install.sh and scripts/install.ps1, so update it to match'
+ )
+
+
+# ------------------------------------------------- agent release coordinates
+#
+# The second half of #101. The Go agent moved out of this monorepo into
+# jhd3197/serverkit-agent and now publishes plain vX.Y.Z releases; nothing here
+# followed it. The panel kept asking jhd3197/ServerKit for `agent-v*` tags that
+# exist in no repo, so /agent/version answered 503 to every agent polling for an
+# update and the served installer downloaded from a 404. Fixing the Dockerfile
+# alone would only have moved the failure one step later.
+
+
+class _FakeResponse:
+ def __init__(self, payload):
+ self._payload = payload
+
+ def raise_for_status(self):
+ return None
+
+ def json(self):
+ return self._payload
+
+
+# Mirrors the real release list, malformed "v" tag and all.
+_RELEASES = [
+ {'tag_name': 'v', 'published_at': 'x', 'html_url': 'u', 'assets': []},
+ {
+ 'tag_name': 'v1.2.0',
+ 'published_at': '2026-01-01T00:00:00Z',
+ 'html_url': 'https://github.com/jhd3197/serverkit-agent/releases/tag/v1.2.0',
+ 'assets': [
+ {'name': 'serverkit-agent-1.2.0-linux-amd64.tar.gz',
+ 'browser_download_url': 'https://example/linux-amd64'},
+ {'name': 'checksums.txt', 'browser_download_url': 'https://example/checksums'},
+ ],
+ },
+ {'tag_name': 'v1.1.0', 'published_at': 'y', 'html_url': 'u', 'assets': []},
+]
+
+
[email protected](autouse=True)
+def _clear_release_cache():
+ """The release lookup memoises for 5 minutes at module scope."""
+ servers_api._releases_cache['data'] = None
+ servers_api._releases_cache['expires'] = None
+ yield
+ servers_api._releases_cache['data'] = None
+ servers_api._releases_cache['expires'] = None
+
+
+def test_agent_repo_default_points_at_the_agent_repo():
+ assert servers_api.AGENT_GITHUB_REPO == 'jhd3197/serverkit-agent'
+
+
+def test_latest_agent_release_queries_the_agent_repo(app):
+ with app.app_context():
+ with patch.object(servers_api.requests, 'get',
+ return_value=_FakeResponse(_RELEASES)) as mock_get:
+ release = servers_api._get_latest_agent_release()
+
+ url = mock_get.call_args[0][0]
+
+ assert 'jhd3197/serverkit-agent' in url, (
+ f'agent releases were requested from {url}; the binaries are published '
+ f'in jhd3197/serverkit-agent'
+ )
+ assert release is not None
+ # "v" must not win, and the tag must not be mangled by a prefix strip.
+ assert release['version'] == '1.2.0'
+ assert release['tag'] == 'v1.2.0'
+ assert release['assets']['linux-amd64'] == 'https://example/linux-amd64'
+
+
+def test_release_lookup_ignores_malformed_and_non_version_tags(app):
+ """A release list with nothing usable must resolve to None, not to ''."""
+ junk = [
+ {'tag_name': 'v', 'published_at': 'x', 'html_url': 'u', 'assets': []},
+ {'tag_name': 'nightly', 'published_at': 'x', 'html_url': 'u', 'assets': []},
+ ]
+ with app.app_context():
+ with patch.object(servers_api.requests, 'get', return_value=_FakeResponse(junk)):
+ assert servers_api._get_latest_agent_release() is None
+
+
+def test_served_install_sh_points_at_the_agent_repo(client):
+ """End of the chain: what the box actually downloads has to exist.
+
+ Asserting on the *served* body, after placeholder substitution -- that is the
+ text `curl | bash` executes.
+ """
+ body = client.get('/api/v1/servers/install.sh').get_data(as_text=True)
+
+ assert 'jhd3197/serverkit-agent' in body
+ # The dead tag scheme must not survive anywhere that becomes a URL.
+ live_agent_v = [
+ line for line in body.splitlines()
+ if 'agent-v' in line and not line.lstrip().startswith('#')
+ ]
+ assert not live_agent_v, f'served installer still builds agent-v* URLs: {live_agent_v}'
+
+
+def test_served_install_ps1_points_at_the_agent_repo(client):
+ body = client.get('/api/v1/servers/install.ps1').get_data(as_text=True)
+
+ assert 'jhd3197/serverkit-agent' in body
+ live_agent_v = [
+ line for line in body.splitlines()
+ if 'agent-v' in line and not line.lstrip().startswith('#')
+ ]
+ assert not live_agent_v, f'served installer still builds agent-v* URLs: {live_agent_v}'