IronPad-Docker/README.md

Ironpad

A local-first, file-based project & knowledge management system.

Ironpad stores all your notes, projects, and tasks as plain Markdown files. No cloud services, no vendor lock-in -- your data stays on your machine in a format you can read and edit with any text editor. Every change is automatically versioned with Git.

v0.2.0 -- Task comments, recurring tasks on calendar, system tray mode, and app branding. See CHANGELOG.md for details.

---

Features

• File-based storage -- All data stored as Markdown files with YAML frontmatter
• Local-first -- Works fully offline, no internet required
• Git integration -- Automatic version control with 60-second commit batching, full diff viewer, push/fetch
• WYSIWYG editing -- Milkdown editor with real-time markdown rendering and formatting toolbar
• Project management -- Organize tasks and notes by project with due dates, tags, subtasks, recurrence, and comments
• Calendar view -- Month grid showing tasks by due date with color-coded urgency; recurring tasks automatically expanded across the month
• Dashboard -- Cross-project overview with active task summaries
• Daily notes -- Quick capture with templates for daily journaling
• Real-time sync -- WebSocket-based live updates; edit in VS Code, see changes in the browser instantly
• External editing -- Full support for VS Code, Obsidian, Vim, or any text editor
• Search -- ripgrep-powered full-text search across all files (Ctrl+K)
• Dark theme -- Beautiful dark UI by default with light mode toggle
• System tray -- Runs quietly in the system tray (Windows, macOS, Linux); no console window in release builds
• Tiny footprint -- 5 MB binary, ~20 MB RAM, sub-second startup

Quick Start

Option 1: Download Release (Recommended)

1. Download the latest release for your platform from Releases
2. Extract and run the executable
3. Your browser opens automatically -- start using Ironpad

Data is stored in a data/ folder next to the executable. To use a custom location, set the IRONPAD_DATA_DIR environment variable.

Option 2: Build From Source

Prerequisites: Rust (1.70+), Node.js (18+), Git

# Clone the repository
git clone https://github.com/OlaProeis/ironPad.git
cd ironPad

# Start the backend
cd backend
cargo run

# In a new terminal, start the frontend
cd frontend
npm install
npm run dev

Open http://localhost:5173 in your browser.

Option 3: Run with Docker (Centralized Server)

This runs Ironpad as a single container that serves both API and frontend on port 3000.

# Build and start in the background
docker compose up -d --build

# View logs
docker compose logs -f

Then open:

• http://localhost:3000 from the same machine, or
• http://<your-server-ip>:3000 from another device on your network.

Data persists in ./data on the host via the compose volume mapping.

To stop:

docker compose down

Docker + Private Git Remote Sync

Ironpad can automatically sync the data/ git repo with a private remote over SSH.

1. Put your SSH key files on the host (example: ./deploy/ssh/id_ed25519 and ./deploy/ssh/id_ed25519.pub).
2. Uncomment the SSH volume mount and git env vars in docker-compose.yml.
3. Set:
   • IRONPAD_GIT_REMOTE_URL (example: git@github.com:your-org/ironpad-data.git)
   • IRONPAD_GIT_SSH_PRIVATE_KEY (path inside container)
   • IRONPAD_GIT_SSH_KNOWN_HOSTS (optional; defaults to /root/.ssh/known_hosts)
   • IRONPAD_GIT_SYNC_INTERVAL_SECS (example: 300)
4. Recreate the stack:

docker compose up -d --build

Sync behavior:

• Every cycle: fetch -> safe fast-forward if possible -> push
• If local and remote diverge, auto fast-forward is skipped and a warning is logged.
• If libgit2 SSH auth fails, Ironpad can fall back to git CLI (controlled by IRONPAD_GIT_USE_CLI_FALLBACK, default true).

Tech Stack

Component	Technology
Backend	Rust, Axum 0.8, Tokio
Frontend	Vue 3, Vite, TypeScript
Editor	Milkdown (ProseMirror-based)
State	Pinia
Routing	Vue Router
Data	Markdown + YAML frontmatter
Version Control	Git (via git2)
Search	ripgrep

Roadmap

Ironpad is under active development. Here's what's planned:

• Task comments and activity summary
• Recurring tasks on calendar (daily/weekly/monthly/yearly expansion)
• System tray mode (Windows, macOS, Linux)
• UI polish and animations
• Tag extraction and filtering across projects
• Backlinks between notes
• Graph view of note connections
• Export to PDF / HTML
• Custom themes
• Global hotkey (Ctrl+Shift+Space)
• Kanban board view for tasks

See CHECKLIST.md for detailed implementation status.

Built With AI

This entire application was built using AI-assisted development -- an approach we call Open Method. We share not just the code, but the complete process: the PRD, task breakdowns, handover documents, and workflow artifacts.

Read about the method:

• The AI Development Workflow I Actually Use -- The original workflow article
• docs/ai-workflow/ -- Documentation of the AI-assisted development process used to build Ironpad

Tools used: Cursor IDE, Claude Opus 4.5/4.6, Context7 MCP

Configuration

Setting	Default	Description
Data directory	data/ next to executable	Override with IRONPAD_DATA_DIR env var
Backend port	3000 (auto-increments to 3010)	Dynamic port selection
Backend host	127.0.0.1	Override with IRONPAD_HOST (use 0.0.0.0 for Docker/server access)
Fixed port	disabled	Set IRONPAD_PORT to force a specific port
Disable tray mode	false	Set IRONPAD_DISABLE_TRAY=1 to run headless in production static mode
Auto-commit	Every 60 seconds	Git commits when changes exist
Git remote URL	not set	IRONPAD_GIT_REMOTE_URL creates/updates origin
Git sync interval	0 (disabled)	Set IRONPAD_GIT_SYNC_INTERVAL_SECS to enable scheduled sync
Git SSH private key	not set	IRONPAD_GIT_SSH_PRIVATE_KEY path to private key in container
Git SSH public key	not set	Optional IRONPAD_GIT_SSH_PUBLIC_KEY path
Git known_hosts path	/root/.ssh/known_hosts	Override with IRONPAD_GIT_SSH_KNOWN_HOSTS
Git SSH username	git	Override with IRONPAD_GIT_SSH_USERNAME if needed
Git SSH passphrase	not set	Optional IRONPAD_GIT_SSH_PASSPHRASE
Git CLI fallback	true	IRONPAD_GIT_USE_CLI_FALLBACK for fetch/push auth fallback
Auto-save	1 second debounce	Frontend saves after typing stops

Documentation

Document	Description
docs/API.md	Complete REST API reference
docs/ARCHITECTURE.md	System design and technical details
docs/ai-workflow/	AI development workflow and methodology

Contributing

This is an early release and contributions are welcome!

1. Check Issues for open bugs and feature requests
2. Create a branch for your feature/fix
3. Follow the code style (cargo fmt for Rust)
4. Test your changes thoroughly
5. Submit a pull request

License

MIT License

Acknowledgments

• Milkdown -- WYSIWYG Markdown editor
• Axum -- Rust web framework
• Vue.js -- Frontend framework
• Pinia -- State management
• Anthropic Claude -- AI-assisted development