diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 000000000..43f893aaf --- /dev/null +++ b/.dockerignore @@ -0,0 +1,46 @@ +# Dependencies +node_modules/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Development +.git/ +.github/ +.vscode/ +.idea/ + +# Build outputs +dist/ +build/ + +# Environment files +.env.local +.env.development +.env.test + +# Testing +coverage/ +.nyc_output/ + +# Misc +*.log +*.swp +*.swo +*~ +.DS_Store +Thumbs.db + +# Documentation +*.md +!README.md + +# CI/CD +.github/ +.gitlab-ci.yml +.travis.yml + +# Docker +#Dockerfile* +#docker-compose* +#.dockerignore diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml new file mode 100644 index 000000000..b18b674aa --- /dev/null +++ b/.github/workflows/docker-publish.yml @@ -0,0 +1,75 @@ +name: Docker Build and Push + +on: + push: + branches: + - main + - master + tags: + - 'v*.*.*' + pull_request: + branches: + - main + - master + workflow_dispatch: + +env: + REGISTRY: ghcr.io + IMAGE_NAME: ${{ github.repository }} + +jobs: + build-and-push: + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + id-token: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log into registry ${{ env.REGISTRY }} + if: github.event_name != 'pull_request' + uses: docker/login-action@v3 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Extract Docker metadata + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + type=ref,event=branch + type=ref,event=pr + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + type=semver,pattern={{major}} + type=sha,prefix=sha- + type=raw,value=latest,enable={{is_default_branch}} + + - name: Build and push Docker image + id: build-and-push + uses: docker/build-push-action@v5 + with: + context: . + push: ${{ github.event_name != 'pull_request' }} + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max + platforms: linux/amd64,linux/arm64 + + - name: Generate artifact attestation + if: github.event_name != 'pull_request' + uses: actions/attest-build-provenance@v1 + with: + subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}} + subject-digest: ${{ steps.build-and-push.outputs.digest }} + push-to-registry: true diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 000000000..3b2778e4e --- /dev/null +++ b/Dockerfile @@ -0,0 +1,91 @@ +FROM node:20-alpine AS builder + +# Install build dependencies +RUN apk add --no-cache \ + python3 \ + make \ + g++ \ + git + +WORKDIR /app + +# Copy package files +COPY package*.json ./ + +# Install all dependencies (including dev dependencies for building) +RUN npm ci && \ + npm cache clean --force + +# Copy source code +COPY . . + +# Build frontend +RUN npm run build + +# ============================================================================= +# Production stage +# ============================================================================= +FROM node:20-alpine + +# Install runtime dependencies including bash and curl for CLI installations +RUN apk add --no-cache \ + python3 \ + make \ + g++ \ + git \ + ca-certificates \ + tzdata \ + bash \ + curl + +WORKDIR /app + +# Copy package files and install production dependencies +COPY package*.json ./ +RUN npm ci --only=production && \ + npm cache clean --force + +# Copy built files from builder +COPY --from=builder /app/dist ./dist +COPY --from=builder /app/server ./server +COPY --from=builder /app/public ./public +COPY --from=builder /app/index.html ./index.html + +# Install all supported CLIs globally +# 1. Claude Code CLI - Anthropic's official CLI +RUN npm install -g @anthropic-ai/claude-code && \ + npm cache clean --force + +# 2. Cursor CLI - Install via official method +RUN curl -fsSL https://cursor.com/install | bash + +# 3. Codex CLI - OpenAI's Codex CLI +RUN npm install -g @openai/codex && \ + npm cache clean --force + +# 4. Taskmaster CLI - AI task orchestration +RUN npm install -g taskmaster-cli && \ + npm cache clean --force + +# Create necessary directories with proper permissions for all CLIs +RUN mkdir -p /data /config /init-scripts /home/node/.claude /home/node/.cursor /home/node/.openai /home/node/.taskmaster && \ + chown -R node:node /app /data /config /init-scripts /home/node/.claude /home/node/.cursor /home/node/.openai /home/node/.taskmaster + +# Copy entrypoint script +COPY --chown=node:node docker-entrypoint.sh /app/docker-entrypoint.sh +RUN chmod +x /app/docker-entrypoint.sh + +# Switch to node user (uid/gid 1000) +USER node + +# Environment variables +ENV NODE_ENV=production \ + PORT=3001 \ + DATABASE_PATH=/data/auth.db \ + CLAUDE_CLI_PATH=claude + +# Expose port +EXPOSE 3001 + +# Start server using entrypoint script +CMD ["/app/docker-entrypoint.sh"] diff --git a/README.md b/README.md index b01ce3562..2992405a3 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,298 @@ cloudcli -p 8080 # Start on custom port cloudcli status # Show current configuration ``` +### Docker Deployment + +Deploy Claude Code UI in a containerized environment with Docker. The container comes with Claude CLI pre-installed and bundled. + +#### Prerequisites + +- [Docker](https://www.docker.com/) v20.10 or higher +- [Docker Compose](https://docs.docker.com/compose/) v2.0 or higher (optional, for orchestration) + +#### Option 1: Pull from GitHub Container Registry (Recommended) + +Use the pre-built multi-platform image (supports amd64 and arm64): + +```bash +# Pull the latest image +docker pull ghcr.io/nickbolles/claudecodeui:latest + +# Run the container +docker run -d \ + --name claudecodeui \ + -p 3002:3001 \ + -v claudecodeui-data:/data \ + -v claudecodeui-config:/config \ + -v claudecodeui-claude:/home/node/.claude \ + -v claudecodeui-cursor:/home/node/.cursor \ + -v claudecodeui-taskmaster:/home/node/.taskmaster \ + -v ./init-scripts:/init-scripts \ + -v ~/Projects:~/Projects \ + -e PORT=3001 \ + -e DATABASE_PATH=/data/auth.db \ + -e CONTEXT_WINDOW=160000 \ + --restart unless-stopped \ + ghcr.io/nickbolles/claudecodeui:latest +``` + +Access the application at `http://localhost:3002` + +#### Option 2: Build from Source + +Build the Docker image locally: + +```bash +# Clone the repository +git clone https://github.com/siteboon/claudecodeui.git +cd claudecodeui + +# Build the image +docker build -t claudecodeui:local . + +# Run the container +docker run -d \ + --name claudecodeui \ + -p 3002:3001 \ + -v claudecodeui-data:/data \ + -v claudecodeui-config:/config \ + -v claudecodeui-claude:/home/node/.claude \ + -v claudecodeui-cursor:/home/node/.cursor \ + -v claudecodeui-taskmaster:/home/node/.taskmaster \ + -v ./init-scripts:/init-scripts \ + -v ~/Projects:~/Projects \ + --restart unless-stopped \ + claudecodeui:local +``` + +#### Option 3: Docker Compose (Recommended for Production) + +Create a `.env` file in the project root: + +```bash +# Server Configuration +PORT=3001 +EXTERNAL_PORT=3002 + +# Database +DATABASE_PATH=/data/auth.db + +# Claude Configuration +CONTEXT_WINDOW=160000 +CLAUDE_CLI_PATH=claude + +# Node Environment +NODE_ENV=production +``` + +Start with docker-compose: + +```bash +# Start the service +docker-compose up -d + +# View logs +docker-compose logs -f + +# Stop the service +docker-compose down + +# Update and restart +docker-compose pull +docker-compose up -d +``` + +#### Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `PORT` | `3001` | Internal application port | +| `DATABASE_PATH` | `/data/auth.db` | SQLite database location | +| `CONTEXT_WINDOW` | `160000` | Claude context window size | +| `CLAUDE_CLI_PATH` | `claude` | Path to Claude CLI executable (pre-installed) | +| `NODE_ENV` | `production` | Node environment mode | + +#### Volume Configuration + +The Docker setup uses several volumes for data persistence: + +| Volume | Purpose | Description | +|--------|---------|-------------| +| `claudecodeui-data` | Application data | SQLite database and user data | +| `claudecodeui-config` | Configuration | Application settings and config files | +| `claudecodeui-claude` | Claude CLI data | Claude authentication and session data | +| `claudecodeui-cursor` | Cursor CLI data | Cursor configuration and settings | +| `claudecodeui-taskmaster` | Taskmaster data | Taskmaster CLI configuration | +| `./init-scripts` | Init scripts | Custom startup scripts (bind mount for easy editing) | +| `~/Projects` | Project files | Mount your local projects (adjust path as needed) | + +**Important**: Adjust the `~/Projects` mount path to match your local project locations. You can add multiple volume mounts for different project directories: + +```bash +-v ~/Projects:~/Projects \ +-v ~/Work:~/Work \ +-v ~/Code:~/Code +``` + +#### Health Checks + +The container includes built-in health monitoring: + +```bash +# Check container health +docker ps + +# View health check logs +docker inspect --format='{{json .State.Health}}' claudecodeui +``` + +The health check queries `http://localhost:3001/api/health` every 30 seconds. + +#### Managing the Container + +```bash +# View logs +docker logs -f claudecodeui + +# Restart container +docker restart claudecodeui + +# Stop container +docker stop claudecodeui + +# Remove container (data persists in volumes) +docker rm claudecodeui + +# View resource usage +docker stats claudecodeui +``` + +#### Initialization Scripts + +The Docker container supports custom initialization scripts that run on startup. This allows you to customize your environment, configure CLIs, and set up tools automatically. + +**Quick Start:** + +1. **Create a custom script** in the `init-scripts/` directory: + ```bash + cat > init-scripts/my-setup.sh <<'EOF' + #!/bin/bash + echo "Setting up my environment..." + git config --global user.name "My Name" + git config --global user.email "me@example.com" + EOF + ``` + +2. **Make it executable:** + ```bash + chmod +x init-scripts/my-setup.sh + ``` + +3. **Restart the container:** + ```bash + docker-compose restart + ``` + +**What's Included:** + +The `init-scripts/` directory contains example scripts for: +- **Claude Code Configuration** - Custom CLI settings +- **Cursor IDE Setup** - Editor preferences +- **Taskmaster Configuration** - AI task orchestration settings +- **Git Configuration** - User settings and aliases +- **Tool Installation** - Additional npm packages and utilities + +All example scripts are disabled by default (you need to uncomment the code to activate them). + +**Supported CLIs:** + +The Docker container includes the following AI CLIs pre-installed: +- **Claude Code CLI** - Anthropic's official Claude CLI (`@anthropic-ai/claude-code`) +- **Cursor CLI** - Cursor's official CLI +- **Codex CLI** - OpenAI's Codex CLI (`@openai/codex`) +- **Taskmaster CLI** - AI task orchestration (`taskmaster-cli`) + +**Usage Tips:** + +- Scripts run in alphabetical order (use number prefixes: `00-`, `01-`, etc.) +- Scripts must be executable (`chmod +x`) +- Scripts run as the `node` user (not root) +- Check container logs for script output: `docker logs claudecodeui` + +For detailed documentation on initialization scripts, see [init-scripts/README.md](init-scripts/README.md). + +#### Troubleshooting Docker Deployment + +**Container won't start:** +- Check logs: `docker logs claudecodeui` +- Verify port 3002 is not already in use: `lsof -i :3002` +- Ensure volumes have proper permissions + +**Cannot access Claude CLI:** +- The Claude CLI is pre-installed in the container +- Authentication data is stored in the `claudecodeui-claude` volume +- First-time setup may require authenticating through the UI + +**Init scripts not running:** +- Verify scripts are executable: `ls -la init-scripts/` +- Check script paths are correct (must be in `init-scripts/` directory) +- View container logs for script output: `docker logs claudecodeui` +- Ensure scripts have proper shebang: `#!/bin/bash` + +**Project files not visible:** +- Verify volume mount paths match your local directories +- Ensure mounted directories have read permissions +- Check docker-compose.yml volume configuration + +### Unraid Deployment + +Deploy Claude Code UI on Unraid servers with the official Community Applications template. + +#### Installation via Community Applications (Recommended - Coming Soon) + +Once approved for Community Applications: + +1. Open Unraid WebUI +2. Navigate to **Apps** tab +3. Search for **"claudecodeui"** or **"Claude Code UI"** +4. Click **Install** +5. Configure settings: + - Set **WebUI Port** (default: 3002) + - Map **project directories** to your Unraid shares + - Adjust **appdata paths** if needed (defaults are fine for most users) +6. Click **Apply** + +Access the WebUI at `http://[UNRAID-IP]:3002` + +#### Manual Template Installation + +Until available in Community Applications, install manually: + +1. Go to **Docker** > **Add Container** +2. Set **Template URL** to: + ``` + https://raw.githubusercontent.com/siteboon/claudecodeui/main/unraid/claudecodeui.xml + ``` +3. Click **Apply** + +#### Configuration Tips + +**Project Directory Mapping:** +- Map your actual project locations (e.g., `/mnt/user/projects`) +- Container paths must match host paths for Claude Code to work +- You can configure up to 3 project directories + +**Default Paths:** +- Application Data: `/mnt/user/appdata/claudecodeui/data` +- Configuration: `/mnt/user/appdata/claudecodeui/config` +- Claude CLI Data: `/mnt/user/appdata/claudecodeui/claude` + +**Port Configuration:** +- Default WebUI Port: `3002` +- Ensure port doesn't conflict with other containers + +For detailed Unraid setup instructions, troubleshooting, and configuration options, see [unraid/README.md](unraid/README.md). + ### Run as Background Service (Recommended for Production) For production use, run Claude Code UI as a background service using PM2 (Process Manager 2): diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 000000000..3cf8eeb31 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,58 @@ +networks: + claudecodeui: + name: claudecodeui + public: + external: true + +services: + claudecodeui: + build: + context: . + dockerfile: Dockerfile + # image: claudecodeui:latest + restart: unless-stopped + ports: + - "${EXTERNAL_PORT:-3002}:3001" + env_file: + - path: ./.env + required: true + environment: + - PORT=${PORT:-3001} + - DATABASE_PATH=${DATABASE_PATH:-/data/auth.db} + - CONTEXT_WINDOW=${CONTEXT_WINDOW:-160000} + - CLAUDE_CLI_PATH=${CLAUDE_CLI_PATH:-claude} + - NODE_ENV=production + volumes: + # Mount project directories for code access + # Adjust these paths to match your local project locations + - ${HOME}/Projects/:${HOME}/Projects/ + # CLI configs and authentication (persisted in named volumes) + - claudecodeui-claude:/home/node/.claude + - claudecodeui-cursor:/home/node/.cursor + - claudecodeui-taskmaster:/home/node/.taskmaster + # Application data persistence + - claudecodeui-data:/data + - claudecodeui-config:/config + # Initialization scripts (bind mount to local directory for easy editing) + - ./init-scripts:/init-scripts + networks: + - claudecodeui + - public + healthcheck: + test: ["CMD", "node", "-e", "require('http').get('http://localhost:3001/api/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 40s + +volumes: + claudecodeui-data: + name: claudecodeui_data + claudecodeui-config: + name: claudecodeui_config + claudecodeui-claude: + name: claudecodeui_claude + claudecodeui-cursor: + name: claudecodeui_cursor + claudecodeui-taskmaster: + name: claudecodeui_taskmaster diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh new file mode 100644 index 000000000..a911b49a2 --- /dev/null +++ b/docker-entrypoint.sh @@ -0,0 +1,44 @@ +#!/bin/bash +set -e + +echo "🚀 Claude Code UI - Container Initialization" +echo "===========================================" + +# Run initialization scripts if they exist +if [ -d "/init-scripts" ] && [ "$(ls -A /init-scripts/*.sh 2>/dev/null)" ]; then + echo "" + echo "📝 Running initialization scripts..." + echo "" + + # Sort and execute all .sh files in /init-scripts + for script in /init-scripts/*.sh; do + if [ -f "$script" ] && [ -x "$script" ]; then + echo "â–ļī¸ Executing: $(basename "$script")" + if bash "$script"; then + echo " ✅ Success: $(basename "$script")" + else + echo " ⚠ī¸ Warning: $(basename "$script") failed with exit code $?" + echo " Continuing anyway..." + fi + echo "" + elif [ -f "$script" ]; then + echo "⚠ī¸ Skipping non-executable script: $(basename "$script")" + echo " Run: chmod +x $(basename "$script") to enable" + echo "" + fi + done + + echo "✅ Initialization scripts completed" + echo "" +else + echo "ℹī¸ No initialization scripts found in /init-scripts" + echo " Create .sh files in /init-scripts to customize your environment" + echo "" +fi + +echo "===========================================" +echo "đŸŽ¯ Starting Claude Code UI Server..." +echo "" + +# Start the Node.js server +exec node server/index.js diff --git a/init-scripts/.gitignore b/init-scripts/.gitignore new file mode 100644 index 000000000..269799cde --- /dev/null +++ b/init-scripts/.gitignore @@ -0,0 +1,8 @@ +# Ignore all shell scripts except examples +*.sh + +# Keep example scripts +!*-example-*.sh + +# Keep the README +!README.md diff --git a/init-scripts/00-example-claude-config.sh b/init-scripts/00-example-claude-config.sh new file mode 100755 index 000000000..3f97d34f5 --- /dev/null +++ b/init-scripts/00-example-claude-config.sh @@ -0,0 +1,29 @@ +#!/bin/bash +# Example: Configure Claude Code CLI settings +# This script demonstrates how to customize Claude Code configuration on container startup + +echo "🔧 Configuring Claude Code CLI..." + +# Example: Set up custom Claude Code configuration +# Uncomment and modify as needed + +# CLAUDE_CONFIG_DIR="/home/node/.claude" +# +# # Create config directory if it doesn't exist +# mkdir -p "$CLAUDE_CONFIG_DIR" +# +# # Example: Create a custom configuration file +# cat > "$CLAUDE_CONFIG_DIR/config.json" < "$CURSOR_CONFIG_DIR/settings.json" < "$TASKMASTER_CONFIG_DIR/config.yaml" < /home/node/.bash_aliases < /home/node/.claude/config.json <> /home/node/.bashrc +``` + +### Clone Repositories + +```bash +#!/bin/bash +if [ ! -d "/workspace/my-repo" ]; then + git clone https://github.com/username/my-repo.git /workspace/my-repo +fi +``` + +## Best Practices + +1. **Idempotency**: Make scripts safe to run multiple times + - Check if files/directories exist before creating them + - Use conditional logic to avoid duplicate operations + +2. **Error Handling**: Add checks for critical operations + ```bash + if ! command -v git &> /dev/null; then + echo "Git is not installed!" + exit 1 + fi + ``` + +3. **Logging**: Add informative echo statements + ```bash + echo "🔧 Configuring Claude Code..." + echo "✅ Configuration complete" + ``` + +4. **Permissions**: Remember the container runs as the `node` user + - Scripts run with `node` user permissions + - Avoid operations requiring root access + - Use user-local paths: `/home/node/...` + +## Environment Variables + +These environment variables are available in your scripts: + +- `NODE_ENV` - Usually "production" +- `PORT` - Application port (default: 3001) +- `DATABASE_PATH` - Database file path +- `CLAUDE_CLI_PATH` - Path to Claude CLI +- `HOME` - User home directory (/home/node) + +## Mounted Volumes + +Your scripts have access to: + +- `/data` - Persistent data storage +- `/config` - Configuration files +- `/init-scripts` - This directory +- `/home/node/.claude` - Claude Code config +- `/home/node/.cursor` - Cursor config +- `/home/node/.taskmaster` - Taskmaster config +- Your project directories (as configured in docker-compose.yml) + +## Troubleshooting + +### Script Not Running + +1. Check if the file is executable: `ls -la init-scripts/` +2. Run: `chmod +x init-scripts/your-script.sh` +3. Check container logs for errors: `docker logs claudecodeui` + +### Script Fails + +1. Check the container logs: `docker logs claudecodeui` +2. Test the script manually: + ```bash + docker exec -it claudecodeui bash + bash /init-scripts/your-script.sh + ``` + +### Permission Denied + +- Scripts run as the `node` user (not root) +- Ensure paths are writable by the `node` user +- Use `/home/node/` paths instead of `/root/` + +## Security Notes + +- **Never commit sensitive data** (API keys, passwords) in init scripts +- Use environment variables or Docker secrets for sensitive configuration +- Review scripts from untrusted sources before running + +## Examples by Tool + +### Claude Code +```bash +#!/bin/bash +mkdir -p /home/node/.claude +echo '{"model": "claude-3-5-sonnet-20241022"}' > /home/node/.claude/config.json +``` + +### Taskmaster +```bash +#!/bin/bash +mkdir -p /home/node/.taskmaster +cat > /home/node/.taskmaster/config.yaml < /home/node/.cursor/settings.json +``` + +## Need Help? + +- Check the example scripts in this directory +- View container logs: `docker logs claudecodeui` +- See the main README.md for Docker setup instructions diff --git a/unraid/README.md b/unraid/README.md new file mode 100644 index 000000000..3dbd808c5 --- /dev/null +++ b/unraid/README.md @@ -0,0 +1,181 @@ +# Claude Code UI - Unraid Template + +This directory contains the Unraid Community Applications template for Claude Code UI. + +## Installation on Unraid + +### Option 1: Via Community Applications (Recommended - Coming Soon) + +Once this template is approved and added to Community Applications: + +1. Open **Unraid WebUI** +2. Go to **Apps** tab +3. Search for **"claudecodeui"** or **"Claude Code UI"** +4. Click **Install** +5. Configure paths and settings (defaults work for most users) +6. Click **Apply** + +### Option 2: Manual Template Installation + +Until the template is available in Community Applications, you can install it manually: + +1. **Open Unraid WebUI** +2. Go to **Docker** tab +3. Click **Add Container** at the bottom +4. Click **Template repositories** at the top +5. Add this repository URL: + ``` + https://github.com/siteboon/claudecodeui + ``` +6. Or manually import the template: + - Switch to **Advanced View** + - Copy the contents of `claudecodeui.xml` from this directory + - Paste into the template editor + +### Option 3: Command Line Template URL + +Add the template URL directly: + +1. Go to **Docker** > **Add Container** +2. Set **Template URL** to: + ``` + https://raw.githubusercontent.com/siteboon/claudecodeui/main/unraid/claudecodeui.xml + ``` +3. Click **Apply** + +## Configuration + +### Required Settings + +| Setting | Default | Description | +|---------|---------|-------------| +| **WebUI Port** | `3002` | Port to access the web interface | +| **Application Data** | `/mnt/user/appdata/claudecodeui/data` | Database and user data | +| **Configuration** | `/mnt/user/appdata/claudecodeui/config` | Config files | +| **Claude CLI Data** | `/mnt/user/appdata/claudecodeui/claude` | Claude authentication | + +### Project Directories + +Configure at least one project directory where your code is located: + +- **Projects Directory 1**: `/mnt/user/projects` (adjust to your location) +- **Projects Directory 2**: Optional additional directory +- **Projects Directory 3**: Optional additional directory + +**Important**: Map your actual project locations. Common Unraid paths: +- `/mnt/user/projects` +- `/mnt/user/development` +- `/mnt/user/code` +- `/mnt/user/docker-projects` + +### Advanced Settings + +| Variable | Default | Description | +|----------|---------|-------------| +| `PORT` | `3001` | Internal container port | +| `DATABASE_PATH` | `/data/auth.db` | Database file location | +| `CONTEXT_WINDOW` | `160000` | Claude context size | +| `CLAUDE_CLI_PATH` | `claude` | CLI executable path | +| `PUID` | `99` | User ID (nobody) | +| `PGID` | `100` | Group ID (users) | + +## First-Time Setup + +1. **Access WebUI**: Navigate to `http://[UNRAID-IP]:3002` +2. **Authenticate Claude CLI**: Follow the on-screen prompts to authenticate with your Anthropic account +3. **Configure Tools**: Enable the Claude Code tools you need in Settings +4. **Add Projects**: Your mounted project directories will be automatically discovered + +## Usage + +### Accessing the Application + +- **WebUI**: `http://[UNRAID-IP]:3002` +- **From Mobile**: Access from any device on your network +- **PWA Support**: Add to home screen for app-like experience + +### Managing the Container + +From Unraid Docker tab: +- **Start/Stop**: Use the container controls +- **Logs**: Click the container icon > **Logs** +- **Console**: Click the container icon > **Console** +- **Update**: Click the container icon > **Force Update** + +## Features + +- **Self-Contained**: Claude CLI is pre-installed in the container +- **Persistent Data**: All data stored in Unraid appdata +- **Multi-Platform**: Supports both amd64 and arm64 +- **Health Checks**: Built-in container health monitoring +- **Auto-Restart**: Configured to restart unless stopped + +## Troubleshooting + +### Container Won't Start + +1. Check logs: Docker tab > Container icon > Logs +2. Verify port 3002 is not in use by another container +3. Check appdata permissions: `/mnt/user/appdata/claudecodeui` + +### Cannot See Projects + +1. Verify project directory paths are correct +2. Check that paths exist on your Unraid system +3. Ensure read/write permissions are set correctly +4. Container paths must match host paths for Claude Code to work properly + +### Cannot Access Claude CLI + +- The Claude CLI is pre-installed in the container +- On first run, you'll need to authenticate through the WebUI +- Authentication data is stored in `/mnt/user/appdata/claudecodeui/claude` + +### Performance Issues + +1. Ensure your Unraid server has adequate resources +2. Check Docker service is running properly +3. Monitor container resource usage in Unraid Dashboard + +## Updating + +The container will automatically pull updates when: +- You click **Force Update** in Unraid Docker tab +- Your Unraid is configured for automatic Docker updates + +To manually update: +1. Go to **Docker** tab +2. Find **claudecodeui** container +3. Click the container icon +4. Select **Force Update** +5. Wait for download and restart + +## Data Backup + +Your data is stored in `/mnt/user/appdata/claudecodeui/`. To backup: + +1. Stop the container +2. Backup the entire `/mnt/user/appdata/claudecodeui` directory +3. Restart the container + +Or use Unraid's built-in backup solutions: +- **CA Backup/Restore Appdata** plugin +- **Unraid backup plugins** + +## Support + +- **Issues**: [GitHub Issues](https://github.com/siteboon/claudecodeui/issues) +- **Documentation**: [Main README](https://github.com/siteboon/claudecodeui#readme) +- **Unraid Forums**: [Community Applications subforum](https://forums.unraid.net/forum/88-docker-containers/) + +## Community Applications Submission + +This template is pending submission to Unraid Community Applications. Once approved, it will be available for one-click installation from the Apps tab. + +## License + +GNU General Public License v3.0 - See [LICENSE](../LICENSE) for details. + +--- + +**Made with care for the Claude Code, Cursor, and Codex community.** diff --git a/unraid/claudecodeui.xml b/unraid/claudecodeui.xml new file mode 100644 index 000000000..fd77cc455 --- /dev/null +++ b/unraid/claudecodeui.xml @@ -0,0 +1,49 @@ + + + claudecodeui + ghcr.io/nickbolles/claudecodeui:latest + https://ghcr.io/nickbolles/claudecodeui + bridge + + sh + false + https://github.com/siteboon/claudecodeui/issues + https://github.com/siteboon/claudecodeui + Use Claude Code, Cursor CLI, or Codex on mobile and web with CloudCLI (aka Claude Code UI). A free open-source web UI that helps you manage your Claude Code, Cursor, or Codex sessions and projects remotely from any device. + +Features: +- Responsive design for desktop, tablet, and mobile +- Interactive chat interface with Claude Code/Cursor/Codex +- Built-in shell terminal access +- File explorer with syntax highlighting +- Git integration for version control +- Session management and history +- Claude CLI pre-installed and bundled + +Access the WebUI at: http://[IP]:[PORT:3002] + Productivity: Tools: + http://[IP]:[PORT:3002] + https://raw.githubusercontent.com/siteboon/claudecodeui/main/unraid/claudecodeui.xml + https://raw.githubusercontent.com/siteboon/claudecodeui/main/public/logo-256.png + --restart=unless-stopped + + + + + + + 3002 + /mnt/user/appdata/claudecodeui/data + /mnt/user/appdata/claudecodeui/config + /mnt/user/appdata/claudecodeui/claude + /mnt/user/projects + + + 3001 + /data/auth.db + 160000 + claude + production + 99 + 100 +