# Local Desktop Docker Guide

This guide helps you run LoreLoom on your own computer with Docker. It is written for writers, hobbyists, and creative testers who may not have used Docker before.

LoreLoom is still early testing software. It is useful for trying the writing workflow, giving feedback, and exploring the project, but it is not production-ready yet.

## What LoreLoom Is

LoreLoom is a local-first writing and worldbuilding workspace. It runs on your own machine, stores your work locally, and is designed to be self-hosted.

Your writing stays on your computer unless you choose to export it, back it up somewhere else, or share it yourself.

## Supported Platforms

LoreLoom currently works best on:

- macOS with Docker Desktop
- Windows with Docker Desktop
- Linux with Docker Engine

If you are new to Docker and use macOS or Windows, Docker Desktop is the easiest path.

## Before You Start

You will need:

- Docker Desktop installed and running, or Docker Engine on Linux
- a copy of the LoreLoom project folder
- a terminal or command prompt

On macOS, the terminal app is called `Terminal`.

On Windows, you can use `PowerShell`, `Command Prompt`, or the terminal built into your code editor.

## Step 1: Install Docker

Download Docker Desktop from:

[https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/)

Install it, then open Docker Desktop once. Leave it running in the background.

On Linux, install Docker Engine using your distribution's normal package instructions.

## Step 2: Get LoreLoom

If you use Git, clone the project:

```bash
git clone <LoreLoom repository URL>
cd LoreLoom
```

If you downloaded LoreLoom as a zip file, unzip it first, then open a terminal inside the LoreLoom folder.

The folder should contain a file named:

```text
compose.yml
```

## Step 3: Start LoreLoom

From the LoreLoom folder, run:

```bash
docker compose -f compose.yml up -d --build
```

The first launch may take a few minutes because Docker needs to build the app.

When it finishes, open:

[http://localhost:8088](http://localhost:8088)

## First Launch

The first time you open LoreLoom, it will ask you to create the first admin account.

This account is local to your LoreLoom install. It is not a cloud account, and it does not create an account with any outside service.

LoreLoom saves your work in two helpful ways:

- browser autosave keeps your current writing state saved locally in the browser
- backend sync stores durable project data in the local LoreLoom backend

This keeps the writing flow fast while giving you another layer of local protection.

## Updating LoreLoom

If you installed LoreLoom with Git, update from the LoreLoom folder:

```bash
git pull
docker compose -f compose.yml down
docker compose -f compose.yml up -d --build
```

Then refresh your browser at:

[http://localhost:8088](http://localhost:8088)

If you downloaded a zip file, download the newer zip, replace the app files, and run the Docker commands again from the new folder.

## Stopping LoreLoom

From the LoreLoom folder, run:

```bash
docker compose -f compose.yml down
```

This stops LoreLoom. Your local data is kept unless you deliberately delete the data folder.

## Backups

LoreLoom includes manual project backup export from inside the app. This is the easiest backup to understand and move around.

Use project backup export when you want a copy of a project that you can keep somewhere safe or import later.

The diagnostics page can also export a diagnostic bundle. This is for technical troubleshooting. It does not include your manuscript or codex content.

LoreLoom's Docker setup also keeps backend data on your own computer. You do not need to understand the database files for normal use, but if you are doing a full local backup, back up the LoreLoom project folder and its data folder together.

## Troubleshooting

### Docker Desktop Is Not Running

If the command says Docker is unavailable or cannot connect, open Docker Desktop and wait for it to finish starting.

Then run:

```bash
docker compose -f compose.yml up -d --build
```

### Port 8088 Is Already In Use

LoreLoom opens at port `8088` by default.

If another app is already using that port, Docker may fail to start the web container. Stop the other app, or edit `compose.yml` and change the left side of this port line to another number:

```yaml
8088:80
```

For example:

```yaml
8090:80
```

Then open:

[http://localhost:8090](http://localhost:8090)

### The App Looks Old After Updating

Try a normal browser refresh first.

If that does not work, use a hard refresh:

- macOS: `Cmd` + `Shift` + `R`
- Windows/Linux: `Ctrl` + `Shift` + `R`

### Restart LoreLoom

From the LoreLoom folder:

```bash
docker compose -f compose.yml down
docker compose -f compose.yml up -d
```

### View Logs

If something is not starting, logs can help:

```bash
docker compose -f compose.yml logs -f
```

You can stop watching logs with `Ctrl` + `C`.

## Getting Help And Sharing Feedback

Join the LoreLoom Discord:

[https://discord.gg/ktUw2gsyAW](https://discord.gg/ktUw2gsyAW)

Use it for:

- help getting started
- bug reports
- suggestions
- tester feedback
- sharing ideas for the writing workflow

If you export a diagnostic bundle, only share it manually when you choose to. LoreLoom does not upload diagnostics automatically.

## What This Guide Does Not Cover

This desktop guide intentionally keeps things simple. It does not cover:

- reverse proxies
- HTTPS certificates
- cloud deployment
- Kubernetes
- production hosting

Those may matter later, but they are not needed for local desktop testing.
