> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/karanhudia/borg-ui/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get Borg UI running and create your first backup in minutes

# Quick Start Guide

Get from zero to your first backup in under 5 minutes using Docker.

<Steps>
  <Step title="Pull and Run Borg UI">
    Run the following command to start Borg UI with Docker:

    ```bash theme={null}
    docker run -d \
      --name borg-web-ui \
      -p 8081:8081 \
      -v borg_data:/data \
      -v borg_cache:/home/borg/.cache/borg \
      -v /home/yourusername:/local:rw \
      ainullcode/borg-ui:latest
    ```

    <Note>
      Replace `/home/yourusername` with the directory you want to back up. This mounts your host directory to `/local` inside the container.
    </Note>

    **What this does:**

    * Maps port 8081 for web access
    * Creates `borg_data` volume for application data (database, SSH keys, logs)
    * Creates `borg_cache` volume for Borg's repository cache (improves performance)
    * Mounts your data directory to `/local` in the container
  </Step>

  <Step title="Access the Web Interface">
    Open your browser and navigate to:

    ```
    http://localhost:8081
    ```

    <Info>
      **Default Login Credentials:**

      * Username: `admin`
      * Password: `admin123`
    </Info>

    You'll be prompted to change the password on first login for security.
  </Step>

  <Step title="Create Your First Repository">
    A repository is where Borg stores your backups. Let's create one:

    1. Click **"Repositories"** in the sidebar
    2. Click **"Create Repository"** button
    3. Fill in the repository details:

    <CodeGroup>
      ```yaml Basic Setup theme={null}
      Repository Name: my-first-backup
      Repository Path: /local/backups/borg-repo
      Repository Type: Local
      Encryption: repokey
      Passphrase: [secure-password]
      ```

      ```yaml Advanced Options theme={null}
      Repository Name: my-first-backup
      Repository Path: /local/backups/borg-repo
      Repository Type: Local
      Encryption: repokey
      Passphrase: [secure-password]
      Compression: lz4  # Fast compression
      ```
    </CodeGroup>

    <Warning>
      **Save your passphrase securely!** If you lose it, your backups are unrecoverable. Borg uses strong encryption with no backdoors.
    </Warning>

    4. Click **"Create"** - the repository will be initialized
  </Step>

  <Step title="Configure Source Directories">
    Now tell Borg what to back up:

    1. In the repository details page, find **"Source Directories"**
    2. Click **"Add Source"**
    3. Enter the path to back up: `/local/Documents` (or any directory you mounted)
    4. Optionally add exclude patterns:
       * `*.tmp`
       * `node_modules`
       * `.git`

    <Info>
      The `/local` prefix corresponds to your mounted volume. If you mounted `/home/yourusername:/local`, then `/local/Documents` backs up `/home/yourusername/Documents` on your host.
    </Info>
  </Step>

  <Step title="Run Your First Backup">
    Time to create your first backup!

    1. Click the **"Backup Now"** button in the repository details
    2. Optionally add a custom archive name or let it auto-generate
    3. Watch the real-time progress:
       * Current file being processed
       * Backup speed (MB/s)
       * Data statistics (original size, compressed, deduplicated)
       * Estimated time remaining

    <img src="https://github.com/user-attachments/assets/de7e870a-2db9-4384-be71-59e8bdd67373" alt="Real-time backup progress" width="800" />

    Your first backup is complete! 🎉
  </Step>
</Steps>

## What's Next?

<CardGroup cols={2}>
  <Card title="Schedule Automatic Backups" icon="clock" href="/guides/scheduling-backups">
    Set up automated backups using the visual cron builder
  </Card>

  <Card title="Browse & Restore Files" icon="folder-open" href="/guides/restore-files">
    Browse your backup archives and restore individual files
  </Card>

  <Card title="Configure Notifications" icon="bell" href="/features/notifications">
    Get alerts via Email, Slack, Discord, and 100+ other services
  </Card>

  <Card title="SSH Remote Backups" icon="server" href="/configuration/ssh-keys">
    Back up to remote servers via SSH/SFTP
  </Card>
</CardGroup>

## Pro Tips

<AccordionGroup>
  <Accordion title="Use Docker Compose for better management">
    Instead of `docker run`, use Docker Compose for easier management:

    Create a `docker-compose.yml` file:

    ```yaml theme={null}
    services:
      borg-ui:
        image: ainullcode/borg-ui:latest
        container_name: borg-web-ui
        restart: unless-stopped
        ports:
          - "8081:8081"
        volumes:
          - borg_data:/data
          - borg_cache:/home/borg/.cache/borg
          - /home/yourusername:/local:rw
        environment:
          - TZ=America/Chicago
          - PUID=1000
          - PGID=1000

    volumes:
      borg_data:
      borg_cache:
    ```

    Then run:

    ```bash theme={null}
    docker compose up -d
    ```

    See the [Installation Guide](/installation) for more options including Redis caching.
  </Accordion>

  <Accordion title="Add Redis for 600x faster archive browsing">
    For large repositories with thousands of files, Redis caching dramatically speeds up archive browsing.

    Update your `docker-compose.yml` to include Redis:

    ```yaml theme={null}
    services:
      borg-ui:
        image: ainullcode/borg-ui:latest
        container_name: borg-web-ui
        restart: unless-stopped
        ports:
          - "8081:8081"
        volumes:
          - borg_data:/data
          - borg_cache:/home/borg/.cache/borg
          - /home/yourusername:/local:rw
        environment:
          - TZ=America/Chicago
          - PUID=1000
          - PGID=1000
          - REDIS_HOST=redis
          - REDIS_PORT=6379
        depends_on:
          redis:
            condition: service_healthy
        networks:
          - borg_network

      redis:
        image: redis:7-alpine
        container_name: borg-redis
        restart: unless-stopped
        command: redis-server --maxmemory 2gb --maxmemory-policy allkeys-lru
        healthcheck:
          test: ["CMD", "redis-cli", "ping"]
          interval: 10s
          timeout: 3s
          retries: 3
        networks:
          - borg_network

    networks:
      borg_network:

    volumes:
      borg_data:
      borg_cache:
    ```

    Learn more in the [Cache Configuration](/configuration/cache) guide.
  </Accordion>

  <Accordion title="Set correct file permissions with PUID/PGID">
    If you encounter permission errors when accessing mounted directories, set the correct user/group IDs:

    1. On your host, run:
       ```bash theme={null}
       id -u && id -g
       ```

    2. Add these as environment variables:
       ```yaml theme={null}
       environment:
         - PUID=1000  # Your user ID
         - PGID=1000  # Your group ID
       ```

    3. Restart the container:
       ```bash theme={null}
       docker compose down && docker compose up -d
       ```

    The container will automatically adjust file permissions to match your host user.
  </Accordion>

  <Accordion title="Mount multiple directories">
    You can mount as many directories as needed:

    ```yaml theme={null}
    volumes:
      - borg_data:/data
      - borg_cache:/home/borg/.cache/borg
      - /home/yourusername:/local/home:rw
      - /var/www:/local/www:ro
      - /mnt/photos:/local/photos:rw
    ```

    Then create backups from:

    * `/local/home/Documents`
    * `/local/www/html`
    * `/local/photos/2024`

    <Info>
      The `/local` prefix is just a convention. You can use any container path, but remember to set `LOCAL_MOUNT_POINTS` environment variable to match:

      ```yaml theme={null}
      environment:
        - LOCAL_MOUNT_POINTS=/local,/data,/custom
      ```
    </Info>
  </Accordion>
</AccordionGroup>

## Common First-Time Questions

<AccordionGroup>
  <Accordion title="Where are my backups actually stored?">
    Your backups are stored in the **repository path** you specified during setup. In our quick start example, that's `/local/backups/borg-repo` inside the container.

    Since `/local` is mapped to `/home/yourusername` on your host, the actual location on your host is:

    ```
    /home/yourusername/backups/borg-repo
    ```

    This is where Borg creates its deduplicated backup repository with all your archives.
  </Accordion>

  <Accordion title="Can I back up to an external drive?">
    Absolutely! Just mount your external drive and point the repository there:

    ```bash theme={null}
    docker run -d \
      --name borg-web-ui \
      -p 8081:8081 \
      -v borg_data:/data \
      -v borg_cache:/home/borg/.cache/borg \
      -v /home/yourusername:/local:rw \
      -v /mnt/external-drive:/backup:rw \
      ainullcode/borg-ui:latest
    ```

    Then create a repository at `/backup/borg-repo`.
  </Accordion>

  <Accordion title="How do I restore files?">
    1. Go to **Repositories** → Select your repository
    2. Click on **Archives** tab
    3. Select the archive (backup snapshot) you want to browse
    4. Navigate through the file tree
    5. Select files/folders and click **"Restore"**
    6. Choose the destination path

    The UI provides a file browser with 600x faster performance when using Redis caching.
  </Accordion>

  <Accordion title="What's the difference between encryption types?">
    Borg UI supports two encryption modes:

    **repokey (Recommended)**

    * Encryption key is stored in the repository
    * Easier to work with on multiple machines
    * Key is backed up with repository
    * Protected by your passphrase

    **keyfile**

    * Encryption key is stored separately on your local machine
    * More secure (key not in repository)
    * You must manage the keyfile yourself
    * Required on each machine accessing the repository

    Both modes use strong encryption (AES-256). Choose `repokey` for simplicity, `keyfile` for maximum security.
  </Accordion>

  <Accordion title="Can I access the container from other devices?">
    Yes! Just replace `localhost` with your server's IP address:

    ```
    http://192.168.1.100:8081
    ```

    <Warning>
      If you can't access it, check your firewall:

      ```bash theme={null}
      sudo ufw allow 8081
      ```
    </Warning>

    For production use, consider setting up a reverse proxy with HTTPS. See the [Reverse Proxy Guide](/deployment/reverse-proxy) for details.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Container won't start">
    Check the container logs:

    ```bash theme={null}
    docker logs borg-web-ui
    ```

    Common issues:

    * Port 8081 already in use → Change to different port: `-p 8082:8081`
    * Volume permission errors → Set PUID/PGID to match your user
  </Accordion>

  <Accordion title="Can't access mounted directories">
    1. Verify the mount path exists on your host
    2. Check container can see the mount:
       ```bash theme={null}
       docker exec borg-web-ui ls /local
       ```
    3. Set correct PUID/PGID:
       ```bash theme={null}
       id -u && id -g
       ```
       Add to environment: `PUID=1000` and `PGID=1000`
  </Accordion>

  <Accordion title="Backup is very slow">
    First backup is always slower due to:

    * Full data read and chunking
    * Building repository cache
    * Calculating deduplication

    Subsequent backups are much faster due to deduplication.

    To speed up:

    1. Use fast compression like `lz4` instead of `zlib` or `lzma`
    2. Exclude unnecessary files (node\_modules, .git, caches)
    3. Ensure good disk I/O on both source and repository
  </Accordion>
</AccordionGroup>

## Next Steps

Now that you have Borg UI running:

1. **[Set up automated backups](/guides/scheduling-backups)** - Use the visual cron builder
2. **[Configure notifications](/features/notifications)** - Get alerts when backups succeed or fail
3. **[Enable Redis caching](/configuration/cache)** - Speed up archive browsing by 600x
4. **[Set up SSH backups](/configuration/ssh-keys)** - Back up to remote servers
5. **[Read security best practices](/advanced/security)** - Keep your backups secure

Have questions? Join our [Discord community](https://discord.gg/5KfVa5QkdQ) for help!