Imperium Maledictum Digital

Appearance

Installation Guide ​

This guide will help you set up the Imperium Maledictum Digital project on your local machine.

Prerequisites ​

Before you begin, ensure you have the following installed:

  • Node.js (v18 or higher) - Download
  • npm (v8 or higher) - Comes with Node.js
  • Git - Download
  • Wrangler CLI (for Cloudflare deployment) - Install with npm install -g wrangler

Clone the Repository ​

bash
# Clone the repository
git clone https://github.com/yourusername/imperium_maledictum.git

# Navigate to the project directory
cd imperium_maledictum

Install Dependencies ​

bash
# Install all project dependencies
npm install

This will install:

  • Vue 3 and related packages
  • Vite build tool
  • Electron (for desktop app)
  • SQLite3 (for desktop storage)
  • VitePress (for documentation)
  • Development dependencies

Platform-Specific Notes ​

Windows ​

If you encounter issues with SQLite3 on Windows:

bash
# Install Windows build tools
npm install --global windows-build-tools

# Rebuild SQLite3
npm rebuild better-sqlite3

macOS ​

If you're on Apple Silicon (M1/M2):

bash
# Ensure you have Rosetta 2 installed
softwareupdate --install-rosetta

# Rebuild native modules
npm rebuild

Linux ​

Install build essentials if not already present:

bash
# Ubuntu/Debian
sudo apt-get install build-essential

# Fedora
sudo dnf install gcc-c++ make

# Arch
sudo pacman -S base-devel

Environment Setup ​

1. Create Local Environment Variables ​

For local development with cloud sync:

bash
# Create a .env.local file
touch .env.local

Add the following to .env.local:

env
VITE_KV_TOKEN=your-test-token-here

2. Cloudflare Worker Configuration ​

If you plan to deploy to Cloudflare:

bash
# Copy the example configuration
cp wrangler.toml.example wrangler.toml

Edit wrangler.toml with your namespace IDs:

toml
[[kv_namespaces]]
binding = "CHARACTERS_KV"
id = "your-characters-kv-id"
preview_id = "your-preview-id"

[[kv_namespaces]]
binding = "JOURNAL_KV"
id = "your-journal-kv-id"
preview_id = "your-preview-id"

[vars]
TOKEN = "your-secret-token"

Verify Installation ​

Run the development server to verify everything is working:

bash
# Start the web development server
npm run dev

You should see:

  VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

Open http://localhost:5173 in your browser. You should see the Imperium Maledictum home page.

Running Different Modes ​

Web Development ​

bash
npm run dev
  • Hot module replacement
  • Fast refresh
  • No cloud sync by default

Desktop Development ​

bash
npm run electron:dev
  • Runs web server and Electron
  • Uses SQLite for storage
  • Full desktop features

Documentation Development ​

bash
npm run docs:dev

Worker Development ​

bash
npm run worker:dev
  • Local Cloudflare Worker
  • Requires wrangler configuration
  • Test cloud sync locally

Build Commands ​

Production Web Build ​

bash
npm run build

Creates optimized build in dist/ directory.

Desktop Application Build ​

bash
npm run electron:build

Creates platform-specific installers in dist_electron/.

Documentation Build ​

bash
npm run docs:build

Creates static documentation in docs/.vitepress/dist/.

Troubleshooting ​

Common Issues ​

Port Already in Use ​

bash
# Kill process using port 5173
# On macOS/Linux:
lsof -ti:5173 | xargs kill -9

# On Windows:
netstat -ano | findstr :5173
taskkill /PID <PID> /F

Module Not Found Errors ​

bash
# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Electron Not Starting ​

bash
# Rebuild Electron
./node_modules/.bin/electron-rebuild

# Or reinstall Electron
npm uninstall electron
npm install electron --save-dev

SQLite Errors ​

bash
# Rebuild better-sqlite3
npm rebuild better-sqlite3

# If that fails, try:
npm uninstall better-sqlite3
npm install better-sqlite3

Getting Help ​

  1. Check the FAQ
  2. Search existing issues
  3. Join our Discord server
  4. Create a new issue with:
    • Node.js version (node --version)
    • npm version (npm --version)
    • Operating system
    • Error messages
    • Steps to reproduce

Next Steps ​