System install docs PR

.github/dependabot.yml

@@ -1,11 +1,41 @@
-# To get started with Dependabot version updates, you'll need to specify which
-# package ecosystems to update and where the package manifests are located.
-# Please see the documentation for all configuration options:
+# Weekly version updates for the manifests this repository actually ships.
 # https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
 
 version: 2
 updates:
-  - package-ecosystem: "" # See documentation for possible values
-    directory: "/" # Location of package manifests
+  - package-ecosystem: "pip"
+    directory: "/"
     schedule:
       interval: "weekly"
+    exclude-paths:
+      - "pyproject.toml"
+    groups:
+      python:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "docker"
+    directories:
+      - "/docker/java"
+      - "/docker/manager"
+      - "/docker/quake-linux"
+      - "/docker/service-console"
+      - "/docker/simple-tcp"
+      - "/docker/steamcmd-linux"
+      - "/docker/wine-proton"
+    schedule:
+      interval: "weekly"
+    groups:
+      images:
+        patterns:
+          - "*"
+        group-by: "dependency-name"

.github/workflows/unittest.yaml

@@ -63,6 +63,15 @@ jobs:
         run: |
           bash ./lint.sh
 
+  system-install-test:
+    runs-on: ubuntu-latest
+    name: system-install-test
+    steps:
+      - name: Checkout AlphaGSM code
+        uses: actions/checkout@v4
+      - name: Run system-wide install test in container
+        run: bash ./system_install_tests/run_system_install_in_container.sh
+
   unit-test:
     runs-on: ubuntu-latest
     needs: build

DEVELOPERS.md

@@ -946,6 +946,9 @@ merge groups, manual dispatch and reusable release validation. Its current gates
 - representative Minecraft backend integration on Windows and macOS
 - four native Windows unit cases, with exact passing JUnit evidence required
   by the final summary; Linux unit and coverage jobs deselect those cases
+- `system-install-test`, which runs
+  [system_install_tests/run_system_install_in_container.sh](system_install_tests/run_system_install_in_container.sh)
+  and checks the Linux system install layout without changing the runner host
 
 Smoke, integration and isolated recheck commands run through
 `scripts/run_ci_workshop_tests.py`. It enables every public anonymous Workshop
@@ -997,6 +1000,28 @@ Important environment variables:
 - `ALPHAGSM_DEBUG`
 
 The smoke tests rely on temporary config files and `ALPHAGSM_CONFIG_LOCATION` to isolate state per run.
+
+Linux install layouts:
+
+- [docs/install/local-user.md](docs/install/local-user.md)
+- [docs/install/system-wide.md](docs/install/system-wide.md)
+
+`src/utils/settings/_settings.py` selects the default config from the program
+path. A frozen binary reads `alphagsm.conf` beside the executable. A source
+tree whose file path starts with `/usr/` reads `/etc/alphagsm.conf`. Every
+other source tree reads `alphagsm.conf` four directories above that settings
+module, which is the repository or install root. `ALPHAGSM_CONFIG_LOCATION`
+replaces that choice.
+
+[scripts/install-system-wide.sh](scripts/install-system-wide.sh) copies the
+tree under `/usr/local/lib/alphagsm`, so the program uses `/etc/alphagsm.conf`.
+On a new config it sets `[downloader] user` to the `alphagsm` account and
+points `db_path` and `target_path` at `/home/alphagsm/downloads`. Server data
+still follows each operator's `~/.alphagsm` user settings. The download helper
+re-executes through `sudo -Hu alphagsm`, and
+`/etc/sudoers.d/gameservers` allows only `alphagsm-downloads` for the
+`alphagsm` group.
+
 GitHub Actions supplies `ALPHAGSM_GITHUB_TOKEN` to smoke and integration jobs
 using the workflow's read-only `GITHUB_TOKEN`; local runs can omit it unless
 they encounter GitHub's anonymous API rate limit.

README.md

@@ -165,6 +165,19 @@ Linux, macOS, or Windows host when that guidance is known, and recommend using
 the Docker runtime instead when you would rather avoid host-side dependency
 setup.
 
+## Install AlphaGSM on Linux
+
+Two scripts copy this repository into place and link the `alphagsm` command.
+They do not install Python packages. Install `requirements-runtime.txt` first.
+Both scripts are Linux only.
+
+- One account: [Local User Install](docs/install/local-user.md)
+- A shared machine: [System-Wide Install](docs/install/system-wide.md)
+
+A system-wide install shares the program and the download cache. Each
+person's servers stay in that person's home. The Fast Start below is the same
+setup when you run `./alphagsm` from a checkout instead of an installed copy.
+
 ## Fast Start
 
 If you want the quickest first run, start with the Docker-manager path above.
@@ -510,9 +523,14 @@ These scripts are useful because they show a full real flow:
 4. check it
 5. stop it cleanly
 
+`bash ./system_install_tests/run_system_install_in_container.sh` checks the
+shared Linux install inside a container. It does not change the host.
+
 ## Step-By-Step Server Guides
 
 - [Documentation Index](docs/README.md)
+- [Local User Install](docs/install/local-user.md)
+- [System-Wide Install](docs/install/system-wide.md)
 - [Everyday Commands](docs/commands.md)
 - [Installing Mods](docs/installing-mods.md)
 - [Updating Servers And AlphaGSM](docs/updating.md)

alphagsm

@@ -2,7 +2,8 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "src"))
+_LAUNCHER = os.path.realpath(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(os.path.dirname(_LAUNCHER), "src"))
 
 if len(sys.argv) == 3 and sys.argv[1] == "--_supervise-process":
     from screen.supervisor import serve

changelog.txt

@@ -7,6 +7,17 @@ server support, CI, packaging, or workflow defaults.
 Historical detail lives in git history. Keep this file focused on release-facing notes and
  high-level milestones.
 
+2026-11-07
+- Install: Linux local and system-wide scripts copy AlphaGSM into place and
+  link `alphagsm`. The command link resolves to the real program so Python
+  can find `src`. A system install reads `/etc/alphagsm.conf`, shares the
+  download cache as the `alphagsm` account, and leaves each operator's
+  servers in that operator's home. A container test checks that layout.
+- Dependencies: Dependabot checks pip, GitHub Actions, and the runtime
+  Dockerfiles every week. Each ecosystem is grouped into one update.
+  `pyproject.toml` stays out of that scan because it only holds tool
+  settings.
+
 2026-11-05
 - ET: Legacy: setup finds the Linux x86_64 tar.gz on the current etlegacy.com
   download page. Release numbers are read from the version label.

docs/README.md

@@ -22,6 +22,8 @@ with `update`.
 | I want to… | Read |
 | --- | --- |
 | Get AlphaGSM installed | [Getting Started](../README.md) |
+| Install AlphaGSM for one Linux account | [Local User Install](install/local-user.md) |
+| Install AlphaGSM once on a shared Linux host | [System-Wide Install](install/system-wide.md) |
 | Take or skip the guided setup tour | [First-run setup](first-run-setup.md) |
 | Run or maintain AlphaGSM with an AI agent | [Agent Operations](agent-operations.md) |
 | See every command (`restore`, `kill`, `activate`, `send`, …) | [Everyday Commands](commands.md) |

docs/install/local-user.md

@@ -0,0 +1,95 @@
+# Local User Install
+
+Use this path on Linux when one person runs AlphaGSM from their own account.
+
+The script copies the repository, writes a config file if you do not already
+have one, and links `alphagsm` into `~/.local/bin`. It does not install Python
+packages, system libraries, Java, or SteamCMD. It does not share downloads
+with other accounts.
+
+Windows and macOS are not covered here. On those systems, run AlphaGSM from a
+checkout or use a standalone binary. See
+[Getting Started](../../README.md).
+
+## Before you run it
+
+Install Python 3 and the runtime packages from the repository:
+
+```bash
+python3 -m pip install -r requirements-runtime.txt
+```
+
+`requirements.txt` is the wider set used for development and tests. A normal
+server only needs `requirements-runtime.txt`.
+
+Game servers may also need Java, 32-bit libraries, or other host packages.
+The [host install requirements](../../README.md#host-install-requirements)
+list the common ones. AlphaGSM reports a missing host package when you start
+a server that needs it.
+
+## Run it
+
+From the repository root:
+
+```bash
+bash ./scripts/install-local-user.sh
+```
+
+The copy leaves out a local `alphagsm.conf`, `env`, `.venv`, and
+`__pycache__`. It keeps `.git` when the checkout has one. Running the script
+again refreshes the copied code and does not replace an existing
+`~/.local/lib/alphagsm/alphagsm.conf`.
+
+## Paths
+
+| Path | Role |
+| --- | --- |
+| `~/.local/lib/alphagsm` | Copied program |
+| `~/.local/bin/alphagsm` | Command link. It points at the copied program, and AlphaGSM follows that link to find `src`. |
+| `~/.local/lib/alphagsm/alphagsm.conf` | Config read by this install |
+
+AlphaGSM chooses that config because the code does not live under `/usr`. A
+copy installed under `/usr`, including `/usr/local`, reads `/etc/alphagsm.conf`
+instead. See [System-Wide Install](system-wide.md).
+
+`ALPHAGSM_CONFIG_LOCATION` still overrides the config file for one command.
+
+If `~/.local/bin` is not already on your `PATH`, add it to your shell profile:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+Open a new shell, then check the command:
+
+```bash
+alphagsm --help
+```
+
+## First server
+
+Follow the [Fast Start](../../README.md#fast-start) commands. Use `alphagsm`
+instead of `./alphagsm` once the link is on your `PATH`. For example:
+
+```bash
+alphagsm mymc create minecraft.vanilla
+alphagsm mymc setup
+alphagsm mymc start
+alphagsm mymc query
+alphagsm mymc stop
+```
+
+Servers, logs, and backups for this account stay under `~/.alphagsm` unless
+the config changes `alphagsm_path`. Downloads stay in this account too. There
+is no shared download user.
+
+## Update the copy
+
+When the install still contains `.git`:
+
+```bash
+git -C "$HOME/.local/lib/alphagsm" pull
+```
+
+Otherwise run `bash ./scripts/install-local-user.sh` again from a newer
+checkout. Neither path edits your existing config file.