docs/setup/linux.md

Rama main · réplica de lectura del repositorio original.

# FlintTrade on Linux (Ubuntu/Debian)

## One-line install (recommended — no prerequisites)

The web-app installer needs nothing pre-installed: no Python, no Node, no git
and no make.

```bash
curl -fsSL https://flinttrade.vercel.app/web-install.sh | bash
```

It downloads a pinned, checksum-verified toolchain (`uv`, Python 3.14, Node and
pnpm) into `~/.flinttrade/tools`, builds FlintTrade from a managed source
checkout at `~/.flinttrade/web-src/FlintTrade`, and installs a
`flinttrade-web` launcher at `~/.local/bin/flinttrade-web`. No `sudo` is used.
The Electron desktop shell keeps its own checkout at `~/.flinttrade/src/FlintTrade`
and its own `~/.local/bin/flinttrade` launcher, so the two installs never
collide and can be run in either order.

### If the site is unreachable (repo-direct fallback)

Use this whenever the command above fails: the hosted URL is only a redirect to
the script in this repository, and a site outage or a deployment without an
immutable source commit answers `503`, which `curl … | bash` would pipe into
your shell as an error page. This form fetches the same script straight from
GitHub and depends on no deployment:

```bash
curl -fsSL https://raw.githubusercontent.com/navaneeshnagarajan/FlintTrade/main/scripts/install/flinttrade-web-install.sh | bash
```

To read the script before running it, clone the repository and run the file:

```bash
git clone https://github.com/navaneeshnagarajan/FlintTrade.git
cd FlintTrade
bash scripts/install/flinttrade-web-install.sh
```

## Uninstall

The plain uninstall removes the application and its launcher integration and
keeps your workspace and data:

```bash
curl -fsSL https://flinttrade.vercel.app/uninstall.sh | bash
```

Add `--purge` to also delete recognised FlintTrade data (workspace, managed
source and tools). Purge is irreversible and asks for typed confirmation:

```bash
curl -fsSL https://flinttrade.vercel.app/uninstall.sh | bash -s -- --purge
```

If the site is unreachable, fetch the same uninstaller straight from GitHub —
the hosted URL is only a redirect to it:

```bash
curl -fsSL https://raw.githubusercontent.com/navaneeshnagarajan/FlintTrade/main/scripts/install/flinttrade-uninstall.sh | bash
```

Or run the same script from a clone or from the managed source checkout
(`~/.flinttrade/web-src/FlintTrade` for the web app,
`~/.flinttrade/src/FlintTrade` for the desktop shell):

```bash
bash scripts/install/flinttrade-uninstall.sh
```

## Electron installer status

The public [download surface](https://flinttrade.vercel.app/download)
distinguishes the source-built web-app install above from Electron-shell
installers. It withholds Electron commands and downloads unless one release
contains the x64 and ARM64 AppImages, the universal macOS DMG, the Windows x64
NSIS installer, and `SHA256SUMS.txt`.

For a release that passes that gate, the one-command install is:

```bash
curl -fsSL https://flinttrade.vercel.app/install.sh | bash
```

The script downloads and verifies the canonical `.AppImage` for your
architecture (x64 or arm64), with an automatic FUSE-less self-extraction
fallback because modern distros no longer ship `libfuse2`. It installs an app icon plus a
`flinttrade` command in `~/.local/bin` (no sudo), and verifies the app
survives launch — the launch log is at
`~/.local/state/flinttrade/desktop-launch.log`. The script lives at
[`scripts/install/`](../../scripts/install/) — read it before piping to a
shell if that is your policy (it should be). If the site is unreachable, run it
repo-direct with
`curl -fsSL https://raw.githubusercontent.com/navaneeshnagarajan/FlintTrade/main/scripts/install/flinttrade-install.sh | bash`.

## Manual `.AppImage` download

Electron releases publish AppImage only; `.deb` and `.rpm` are not part of the
new four-installer contract.

To build the installer locally:

```bash
pnpm install --frozen-lockfile
python scripts/ft.py desktop-test
python scripts/ft.py desktop-package
```

`make desktop-test` and `make desktop-package` are the POSIX aliases for the
same two targets. Generated packages live under
`packages/apps/desktop/release/electron/`.

## Source development

Requires Python `>=3.14`, Node.js `>=22.23.4`, `uv`, pnpm 10.34.5, Git, and
optionally Rust for `core/ticks`. Those floors come from `[requirements]` in
`flint.toml`, which is the single source of truth for them. Ubuntu releases
before 26.04 do not ship Python 3.14 — use Ubuntu 26.04, or the one-line
installer, which provisions its own interpreter.

pnpm is pinned in the root `package.json` `packageManager` field, so install it
directly (`npm install -g pnpm@10.34.5`) — Corepack still works if your Node
bundles it, but Node dropped Corepack in 25.0.0, so it is an optional
accelerator rather than a prerequisite.

To run the built web app from source:

```bash
git clone https://github.com/navaneeshnagarajan/FlintTrade.git
cd FlintTrade
uv sync
pnpm install
pnpm --filter @flinttrade/terminal build
python scripts/ft.py start
```

Then open http://127.0.0.1:5100. The terminal build step is not optional: the
backend serves the UI only when `packages/apps/terminal/dist/index.html`
exists, so skipping it leaves you with an API and no interface.

To run the Vite dev server alongside the backend instead:

```bash
python scripts/ft.py setup
python scripts/ft.py dev
```

Then open http://localhost:5173. `python scripts/ft.py <target>` works on
every OS; `make <target>` is the POSIX alias for the same targets.

## Server services (advanced)

`infra/scripts/setup-production.sh` is the Ubuntu 26.04 LTS production installer
(Python >= 3.14). A checkout of this repository is only the *script* source;
the installer provisions `/opt/flinttrade` itself. The unit is hardcoded to
that prefix (`ProtectHome=true`). There is no directory override.

The installer creates `/opt/flinttrade/.venv`, installs the hashed
`requirements.lock` into it, builds `packages/apps/terminal/dist` with the
pinned pnpm, and provisions the credential-vault `master_password` as
`www-data` so a non-interactive `python -m flinttrade_core.app` can start
and serve the UI. It chowns only the runtime workspace, data and log paths
to `www-data`. The git checkout and `.venv` stay root-owned so
`infra/scripts/deploy.sh` can update them. See
[the systemd notes](../../infra/systemd/README.md).

```bash
sudo bash infra/scripts/setup-production.sh
sudoedit /opt/flinttrade/.env
sudo systemctl start flinttrade
```

Edit `/opt/flinttrade/.env` with `sudoedit` only for server-only fallback
values that cannot be supplied through the app UI. Then complete Setup in
the app at http://127.0.0.1:5100. The installer builds the terminal; the
backend serves that UI only when `packages/apps/terminal/dist/index.html`
exists.

Raspberry Pi OS Bookworm (system Python 3.11) is not this path — use the
one-line installer above, or `infra/install/install-native.sh`.