Magent/docs/LOCAL_DEVELOPMENT.md

# Foreground installation: Linux, macOS and Windows

This runs Magent directly from source without Docker or Portainer. It is useful
for local evaluation and development; closing the terminals stops the services.
For a Linux service that starts at boot, use [native production](NATIVE_INSTALL.md).
No Windows Service or macOS launchd package is supplied. Use a private local
directory, not a shared/synced folder containing real production data.

Install Python **3.14**, Node.js **24** with npm, and Git. The commands below are
split by shell; do not paste Bash line continuations into PowerShell. Do not
connect a development checkout to production credentials/databases.

## Get the source and dependencies

Linux/macOS (Bash/zsh):

```sh
git clone --branch release --single-branch https://git.amslabs.net/Rephl3x/Magent.git magent
cd magent
python3.14 -m venv .venv
.venv/bin/python -m pip install -r backend/requirements.txt
```

Windows (PowerShell, with Python's `py` launcher installed):

```powershell
git clone --branch release --single-branch https://git.amslabs.net/Rephl3x/Magent.git magent
Set-Location magent
py -3.14 -m venv .venv
& .\.venv\Scripts\python.exe -m pip install -r backend\requirements.txt
```

If `py` is unavailable, use the full path to your Python 3.14 executable instead.
No activation script or machine-wide execution-policy change is required. Confirm
`node --version` reports 24.x. Native dependency installation may need compiler
prerequisites when wheels are unavailable for your CPU/OS.

## Configure the backend

For a fresh local database, generate three independent values in your **private
terminal**. Replace `python3.14` below with `py -3.14` on Windows:

```sh
python3.14 -c "import secrets; print(secrets.token_urlsafe(48))"
python3.14 -c "import secrets; print(secrets.token_urlsafe(48))"
python3.14 -c "import base64,secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())"
```

The first is `JWT_SECRET`, the second is `SETUP_TOKEN`, and the third is
`SETTINGS_ENCRYPTION_KEY`. Do not paste them into chat/logs/issues. In an editor,
create `backend/.env` with the following contents, replacing all three placeholders:

```dotenv
JWT_SECRET=PASTE_FIRST_RANDOM_VALUE
SETUP_TOKEN=PASTE_SECOND_RANDOM_VALUE
SETTINGS_ENCRYPTION_KEY=PASTE_THIRD_RANDOM_VALUE
MAGENT_MANAGED_SECRETS=false
MAGENT_APPLICATION_URL=http://127.0.0.1:3000
CORS_ALLOW_ORIGIN=http://127.0.0.1:3000
AUTH_COOKIE_SECURE=false
API_DOCS_ENABLED=false
SQLITE_PATH=data/magent.db
LOG_FILE=data/magent.log
BRANDING_SOURCE=data
```

On Linux/macOS restrict the file with `chmod 600 backend/.env` and use a private
checkout (`umask 077` before creating local data). On Windows restrict the folder
and `.env` to your account using NTFS security permissions; Unix `chmod` is not
a substitute for Windows ACLs. The repository ignores `backend/.env` and
`backend/data/`, but Git ignore rules are not encryption or access control.

Use the same keys and database when restarting. Do not recreate `.env` during an
upgrade. For isolated testing without background imports, add
`BACKGROUND_TASKS_ENABLED=false`; omit it for normal operation after setup.
Keep `ADMIN_PASSWORD` and `MAGENT_RUNTIME_MANAGED` unset.

These examples deliberately use **127.0.0.1**, not `localhost`. Open that exact
origin in the browser; mixing the names can break origin checks/cookies.

## Terminal 1: start the API

Start in the checkout root. The working directory below puts all local data in
`backend/data`. `--env-file` explicitly loads the private file; the application
does not discover it automatically.

Linux/macOS:

```sh
cd backend
../.venv/bin/python -m uvicorn app.main:app --env-file .env --host 127.0.0.1 --port 8000 --workers 1
```

Windows PowerShell:

```powershell
Set-Location backend
& ..\.venv\Scripts\python.exe -m uvicorn app.main:app --env-file .env --host 127.0.0.1 --port 8000 --workers 1
```

Leave this process running. There must be only one backend instance using the
database. `--reload` is intentionally not used for installation/restore checks.

## Terminal 2: build and start the web frontend

Open a second terminal at the checkout root. The API address must be set before
building because it is compiled into the frontend's rewrites. The application
URL must also be present in the frontend runtime for this deliberate HTTP mode.
Do not load the backend `.env` into this terminal.

Linux/macOS:

```sh
cd frontend
export BACKEND_INTERNAL_URL=http://127.0.0.1:8000
export NEXT_PUBLIC_API_BASE=/api
export NEXT_TELEMETRY_DISABLED=1
export MAGENT_APPLICATION_URL=http://127.0.0.1:3000
npm ci --include=dev
NODE_ENV=production npm run build
cp -R public .next/standalone/
cp -R .next/static .next/standalone/.next/
HOSTNAME=127.0.0.1 PORT=3000 NODE_ENV=production node .next/standalone/server.js
```

Windows PowerShell:

```powershell
Set-Location frontend
$env:BACKEND_INTERNAL_URL = 'http://127.0.0.1:8000'
$env:NEXT_PUBLIC_API_BASE = '/api'
$env:NEXT_TELEMETRY_DISABLED = '1'
$env:MAGENT_APPLICATION_URL = 'http://127.0.0.1:3000'
$env:NODE_ENV = 'production'
npm.cmd ci --include=dev
npm.cmd run build
Copy-Item -LiteralPath public -Destination .next\standalone\ -Recurse -Force
Copy-Item -LiteralPath .next\static -Destination .next\standalone\.next\ -Recurse -Force
$env:HOSTNAME = '127.0.0.1'
$env:PORT = '3000'
node .next\standalone\server.js
```

Only continue to the next command after the previous one succeeds. The standalone
server needs both copied asset directories; a successful HTML response without
them can still produce an unstyled, unusable page.

For actual frontend development, stop the standalone server and use
`npm run dev -- --hostname 127.0.0.1 --port 3000` with the same backend/public URL
variables. On PowerShell set `$env:NODE_ENV = 'development'` first and use
`npm.cmd run dev -- --hostname 127.0.0.1 --port 3000`; on POSIX prefix the command
with `NODE_ENV=development`. Do not expose the development server
publicly or treat a dev-mode test as a production-build test.

## Verify, set up and retain data

Open `http://127.0.0.1:3000/api/health` (expect `{"status":"ok"}`), then
`http://127.0.0.1:3000/setup`. Enter your `SETUP_TOKEN`, create the administrator
and configure apps. The setup help dialog's container command is not used here;
use the token from your manual `.env`. Remove only `SETUP_TOKEN` after creating
the administrator and restart the API.

Inspect the browser console/network panel for failed scripts, styles or API
requests. Check `/api/setup/status` and a successful sign-in. Restart both
processes and verify the account and settings remain; do not create a second
database accidentally by starting the backend from a different directory.

Ctrl+C stops each process. Keep **backend/data and backend/.env together** for
this local installation. Source deletion, `git clean` or a new checkout does not
preserve untracked data for you. For upgrades, back up first, stop both processes,
update the source/dependencies, rebuild and copy the frontend assets again, then
restart with the original state and keys.

Portable [backup/restore](installation-and-recovery.md) works here too. Restart
the API process after staging a restore and recheck the destination URL. Take
offline snapshots only while the backend is stopped. To move a trial into
production, follow the native/container guide for a fresh destination and restore
a compatible encrypted backup; do not copy a Windows venv or native frontend
dependencies into a Linux installation.