umbrel-apps/nx-webmail/README.md

Standalone Webmail (Docker-ready)

Local setup

1. Install dependencies: npm install
2. Run dev mode (Vite + API): npm run dev
3. Open: http://localhost:5173

Docker (standalone)

1. Copy env file: cp .env.example .env
2. Build + run: docker compose up --build -d
3. Open: http://localhost:3001

Publish image for Umbrel

Umbrel installation is most reliable when your app uses a prebuilt image from a registry.

1. Recommended: use the GitHub Action .github/workflows/publish-nx-webmail-image.yml.
   • For Gitea use .gitea/workflows/publish-nx-webmail-image.yml.
   • Required Gitea secrets: GITEA_USERNAME, GITEA_TOKEN.
2. The workflow reads version from nx-webmail/umbrel-app.yml and publishes:
   • git.weektab.org/nexus/nx-webmail:<version>
   • git.weektab.org/nexus/nx-webmail:latest
3. The workflow then pins nx-webmail/docker-compose.yml to tag@sha256:digest automatically.
4. Manual fallback: docker buildx build --platform linux/amd64,linux/arm64 -t git.weektab.org/nexus/nx-webmail:1.0.3 --push .

Umbrel app packaging

This repository is prepared for Umbrel app-store usage.

1. Keep this app in a folder named exactly like the app ID: nx-webmail.
2. Keep these files in that folder:
   • docker-compose.yml
   • umbrel-app.yml
   • Dockerfile
   • exports.sh
3. Ensure your store root contains umbrel-app-store.yml.
4. Push the app-store repo to a git host reachable from Umbrel.

Install from Umbrel UI

1. Open App Store in Umbrel.
2. Use the menu to add a Community App Store.
3. Paste your repository URL.
4. Open your store and install Webmail.

Notes:

• Umbrel uses the app_proxy service in docker-compose.yml.
• Internal app port is 3001.
• server uses a prebuilt registry image (git.weektab.org/nexus/nx-webmail:1.0.3).
• If your store prefix changes, update id in umbrel-app.yml and APP_HOST in docker-compose.yml.

Notes

• Frontend calls API on /api/webmail/*.
• IMAP/SMTP credentials are provided by user login in UI.