# Iron

Iron is a self-hosted personal cloud drive gateway. It provides one logical file
namespace over local storage and pluggable backends, with a browser UI for daily
file management and operational visibility.

The project is currently a **Product MVP Candidate**: the core backend and Web
app exist, but the release still needs hardening, broader browser regression
coverage, and more real-world usage.

![Iron demo](docs/assets/iron-demo.gif)

## Features

- FastAPI backend with SQLite, SQLAlchemy, and Alembic migrations
- Local authentication with persisted bearer-token sessions
- Directory and file operations: browse, create folder, rename, move, delete,
  restore, download, and preview
- `tus` upload flow with local object persistence
- Desktop-first Vue Web app at `/app`, using the OpenCloud design system
- Storage backend management for local directories, S3 storage, and
  OpenList/WebDAV runtime paths
- Placement policies, reconcile jobs, health checks, and retryable background jobs
- Metadata export, validation, integrity checks, restore plans, and guarded import
- Python Playwright end-to-end coverage for core browser flows
- Real-environment OpenList acceptance scripts for deployment validation

## Quick Start

Iron uses `uv` for local Python environment setup.

```bash
UV_CACHE_DIR=.uv-cache uv venv .venv
UV_CACHE_DIR=.uv-cache uv pip install --python .venv/bin/python -e '.[dev]'
npm install
npm run build
.venv/bin/python -m uvicorn app.main:app --reload
```

Open the Web app:

```text
http://127.0.0.1:8000/app
```

Default local bootstrap credentials:

```text
username: admin
password: changeme-iron
```

For a practical local deployment with OpenList and Aliyun Drive, start with
[docs/openlist-local-deployment-sop.md](docs/openlist-local-deployment-sop.md).

## Configuration

Common environment variables:

- `IRON_DATABASE_URL`
- `IRON_BOOTSTRAP_USERNAME`
- `IRON_BOOTSTRAP_PASSWORD`
- `IRON_SECRET_KEY`
- `IRON_AUTH_SESSION_TTL_HOURS`
- `IRON_UPLOAD_TEMP_DIR`
- `IRON_LOCAL_STORAGE_DIR`
- `IRON_CACHE_DIR`
- `IRON_JOB_POLL_INTERVAL_SECONDS`
- `IRON_JOB_BATCH_SIZE`

Runtime data is intentionally ignored by Git. By default, local development may
create `.iron-storage/`, `.iron-temp/`, `iron.db`, and `output/`.

`IRON_SECRET_KEY` encrypts stored backend credentials such as S3 keys and
WebDAV passwords. Override the development default before using real storage
credentials.

## Development

Build the frontend:

```bash
npm run build
```

Run the full test suite:

```bash
.venv/bin/python -m pytest
```

Current expected result:

```text
78 passed
```

Run the real OpenList acceptance suite against a live local deployment:

```bash
.venv/bin/python scripts/real_openlist_suite.py
```

Run the browser E2E flow directly:

```bash
.venv/bin/python scripts/ui_playwright_smoke.py
```

Regenerate the README demo GIF:

```bash
.venv/bin/python scripts/generate_readme_demo.py
```

Or through pytest:

```bash
.venv/bin/python -m pytest tests/e2e/test_web_ui_playwright.py
```

Playwright screenshots and runtime artifacts are written to `output/playwright/`.

## Repository Layout

```text
app/                 FastAPI application, services, repositories, schemas
alembic/             Database migrations
frontend/            Vite + Vue + TypeScript source
app/web/dist/        Built frontend assets served by FastAPI
scripts/             Local automation and E2E scripts
deploy/              OpenList compose, Iron env templates, and systemd examples
tests/               Backend, API, and browser E2E tests
docs/                Product, architecture, API, and maintenance docs
```

## Documentation

Start with:

- [Documentation index](docs/README.md)
- [Product](docs/product.md)
- [Architecture](docs/architecture.md)
- [API](docs/api.md)
- [Development](docs/development.md)
- [OpenList + Iron Local Deployment SOP](docs/openlist-local-deployment-sop.md)

For contribution workflow, see [CONTRIBUTING.md](CONTRIBUTING.md).
For AI/coding-agent guidance, see [AGENTS.md](AGENTS.md).

## Security Notes

Iron is not yet a hardened public Internet service. Treat the current credentials
and local bearer-token session model as development-oriented defaults. Change the
bootstrap password and review deployment boundaries before exposing the service.

Metadata import is guarded and requires both:

- `confirm_replace=true`
- a fresh validation token from `POST /api/exports/metadata/restore-plan`

## License

No open source license has been selected yet. Add a `LICENSE` file before
publishing or accepting external contributions.