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

# Systemd Service

> Run copyparty as a systemd service on Linux

## Overview

Running copyparty as a systemd service ensures it starts automatically on boot and can be managed using standard systemd commands. This guide covers installation and configuration of copyparty as both a system-wide and user service.

## System Service Installation

<Steps>
  <Step title="Download copyparty">
    Download the latest copyparty SFX to `/usr/local/bin`:

    ```bash theme={null}
    wget https://github.com/9001/copyparty/releases/latest/download/copyparty-sfx.py -O /usr/local/bin/copyparty-sfx.py
    chmod +x /usr/local/bin/copyparty-sfx.py
    ```

    Or if installed via package manager:

    ```bash theme={null}
    # Arch Linux
    pacman -S copyparty

    # Homebrew
    brew install copyparty
    ```
  </Step>

  <Step title="Create copyparty user">
    Create a dedicated user for running the service:

    ```bash theme={null}
    useradd -r -s /sbin/nologin -m -d /var/lib/copyparty copyparty
    ```
  </Step>

  <Step title="Configure firewall">
    Open the required ports:

    ```bash theme={null}
    # For HTTP only
    firewall-cmd --permanent --add-port=3923/tcp

    # For all features (HTTP, FTP, SFTP, TFTP, etc.)
    firewall-cmd --permanent --add-port={80,443,3921,3922,3923,3945,3990}/tcp
    firewall-cmd --permanent --add-port=12000-12099/tcp  # FTP passive mode
    firewall-cmd --permanent --add-port={69,1900,3969,5353}/udp  # TFTP, SSDP, mDNS

    firewall-cmd --reload
    ```
  </Step>

  <Step title="Install service file">
    Download and install the systemd service file:

    ```bash theme={null}
    wget https://raw.githubusercontent.com/9001/copyparty/hovudstraum/contrib/systemd/copyparty.service
    cp copyparty.service /etc/systemd/system/
    ```

    Or create `/etc/systemd/system/copyparty.service` with the following content:

    ```ini theme={null}
    [Unit]
    Description=copyparty file server

    [Service]
    Type=notify
    SyslogIdentifier=copyparty
    Environment=PYTHONUNBUFFERED=x
    ExecReload=/bin/kill -s USR1 $MAINPID
    PermissionsStartOnly=true

    # User to run as + where the TLS certificate is (if any)
    User=copyparty
    Group=copyparty
    WorkingDirectory=/var/lib/copyparty
    Environment=XDG_CONFIG_HOME=/var/lib/copyparty/.config

    # OPTIONAL: allow copyparty to listen on low ports (80/443)
    AmbientCapabilities=CAP_NET_BIND_SERVICE

    # Security hardening
    MemoryMax=50%
    MemorySwapMax=50%
    ProtectClock=true
    ProtectControlGroups=true
    ProtectHostname=true
    ProtectKernelLogs=true
    ProtectKernelModules=true
    ProtectKernelTunables=true
    ProtectProc=invisible
    RemoveIPC=true
    RestrictNamespaces=true
    RestrictRealtime=true
    RestrictSUIDSGID=true

    # Create logs directory
    LogsDirectory=copyparty

    # Start copyparty
    ExecStart=/usr/bin/python3 /usr/local/bin/copyparty-sfx.py -c /etc/copyparty.conf

    # If installed from package manager, use:
    # ExecStart=/usr/bin/copyparty -c /etc/copyparty.conf

    [Install]
    WantedBy=multi-user.target
    ```
  </Step>

  <Step title="Create configuration file">
    Create `/etc/copyparty.conf` with your settings:

    ```yaml theme={null}
    [global]
      e2dsa  # enable file indexing
      e2ts   # enable multimedia indexing
      ansi   # colors in log messages
      
      # Log to file instead of journalctl
      q, lo: $LOGS_DIRECTORY/%Y-%m%d.log
      
      # Uncomment to listen on ports 80/443 (requires CAP_NET_BIND_SERVICE)
      # p: 80,443,3923

    [accounts]
      admin: your_password_here

    [/]
      /var/lib/copyparty-jail
      accs:
        r: *
        rwmda: admin
      flags:
        grid
    ```

    <Warning>
      The default configuration provides read access to everyone and full access to the `admin` user. Customize permissions according to your security requirements.
    </Warning>
  </Step>

  <Step title="SELinux configuration (Fedora/RHEL)">
    If using SELinux:

    ```bash theme={null}
    restorecon -vr /etc/systemd/system/copyparty.service
    ```
  </Step>

  <Step title="Enable and start service">
    ```bash theme={null}
    systemctl daemon-reload
    systemctl enable --now copyparty
    ```
  </Step>

  <Step title="Verify service status">
    Check that the service is running:

    ```bash theme={null}
    systemctl status copyparty

    # View logs
    journalctl -u copyparty -f

    # Or if logging to file:
    tail -f /var/log/copyparty/$(date +%Y-%m%d).log
    ```
  </Step>
</Steps>

## User Service Installation

For running copyparty as a regular user without root privileges:

<Steps>
  <Step title="Install user service file">
    Create `~/.config/systemd/user/copyparty.service`:

    ```ini theme={null}
    [Unit]
    Description=copyparty file server

    [Service]
    Type=notify
    SyslogIdentifier=copyparty
    WorkingDirectory=/var/lib/copyparty-jail
    Environment=PYTHONUNBUFFERED=x
    Environment=PRTY_CONFIG=%h/.config/copyparty/copyparty.conf
    ExecReload=/bin/kill -s USR1 $MAINPID

    # Ensure config exists
    ExecStartPre=/bin/bash -c 'if [[ ! -f %h/.config/copyparty/copyparty.conf ]]; then mkdir -p %h/.config/copyparty; cp /etc/copyparty/copyparty.conf %h/.config/copyparty/copyparty.conf; fi'

    # Run copyparty
    ExecStart=/usr/bin/python3 /usr/bin/copyparty

    [Install]
    WantedBy=default.target
    ```
  </Step>

  <Step title="Create user configuration">
    Create `~/.config/copyparty/copyparty.conf` with your settings.
  </Step>

  <Step title="Enable user service">
    ```bash theme={null}
    systemctl --user daemon-reload
    systemctl --user enable --now copyparty

    # Enable linger to start service on boot without login
    loginctl enable-linger $USER
    ```
  </Step>
</Steps>

## Multi-Instance Setup

Run multiple copyparty instances with different configurations using template services:

<Steps>
  <Step title="Create template service">
    Create `/etc/systemd/system/copyparty@.service`:

    ```ini theme={null}
    [Unit]
    Description=copyparty file server

    [Service]
    Type=notify
    SyslogIdentifier=copyparty
    WorkingDirectory=/var/lib/copyparty-jail
    Environment=PYTHONUNBUFFERED=x
    Environment=PRTY_CONFIG=/etc/copyparty/copyparty.conf
    ExecReload=/bin/kill -s USR1 $MAINPID

    # %i = instance name (e.g., copyparty@alice -> %i = alice)
    User=%i
    Environment=XDG_CONFIG_HOME=/home/%i/.config

    ExecStart=/usr/bin/python3 /usr/bin/copyparty

    [Install]
    WantedBy=multi-user.target
    ```
  </Step>

  <Step title="Start instance for specific user">
    ```bash theme={null}
    systemctl enable --now copyparty@alice
    systemctl enable --now copyparty@bob
    ```
  </Step>
</Steps>

## Chroot (prisonparty) Setup

For enhanced security, run copyparty in a chroot environment:

<Steps>
  <Step title="Download prisonparty script">
    ```bash theme={null}
    wget https://raw.githubusercontent.com/9001/copyparty/hovudstraum/bin/prisonparty.sh -O /usr/local/bin/prisonparty.sh
    chmod +x /usr/local/bin/prisonparty.sh
    ```
  </Step>

  <Step title="Create jail directory">
    ```bash theme={null}
    mkdir -p /var/lib/copyparty-jail
    ```
  </Step>

  <Step title="Install prisonparty service">
    Create `/etc/systemd/system/prisonparty.service`:

    ```ini theme={null}
    [Unit]
    Description=copyparty file server

    [Service]
    SyslogIdentifier=prisonparty
    Environment=PYTHONUNBUFFERED=x
    WorkingDirectory=/var/lib/copyparty-jail
    ExecReload=/bin/kill -s USR1 $MAINPID

    # Prevent systemd-tmpfiles-clean from deleting copyparty
    ExecStartPre=+/bin/bash -c 'mkdir -p /run/tmpfiles.d/ && echo "x /tmp/pe-copyparty*" > /run/tmpfiles.d/copyparty.conf'

    # Run in chroot: args are [jail_dir] [user] [group] [mount_points...] -- [copyparty args...]
    ExecStart=/bin/bash /usr/local/bin/prisonparty.sh /var/lib/copyparty-jail cpp cpp \
      /mnt \
      -- \
      /usr/bin/python3 /usr/local/bin/copyparty-sfx.py -q -v /mnt::rw

    [Install]
    WantedBy=multi-user.target
    ```

    <Warning>
      The chroot setup provides additional isolation but requires careful configuration of mounted directories.
    </Warning>
  </Step>

  <Step title="Enable and start">
    ```bash theme={null}
    systemctl daemon-reload
    systemctl enable --now prisonparty
    ```
  </Step>
</Steps>

## Service Management

### Common Commands

```bash theme={null}
# Start service
systemctl start copyparty

# Stop service
systemctl stop copyparty

# Restart service
systemctl restart copyparty

# Reload configuration (no downtime)
systemctl reload copyparty
# or
kill -s USR1 $(pidof copyparty)

# View status
systemctl status copyparty

# View logs
journalctl -u copyparty -f

# Enable on boot
systemctl enable copyparty

# Disable on boot
systemctl disable copyparty
```

### Configuration Reload

Copyparty supports reloading accounts and volumes without restarting:

```bash theme={null}
# Reload configuration
systemctl reload copyparty
```

<Note>
  Changes to the `[global]` section require a full restart to take effect.
</Note>

## Troubleshooting

### Service Won't Start

1. Check service status:
   ```bash theme={null}
   systemctl status copyparty
   ```

2. View detailed logs:
   ```bash theme={null}
   journalctl -u copyparty -n 100
   ```

3. Verify configuration:
   ```bash theme={null}
   /usr/bin/python3 /usr/local/bin/copyparty-sfx.py -c /etc/copyparty.conf --help
   ```

### Thumbnails Not Working

If thumbnails aren't working, try removing the security hardening options temporarily:

```ini theme={null}
# Comment out these lines in the service file:
# ProtectClock=true
# ProtectControlGroups=true
# ...
```

Then reload and restart:

```bash theme={null}
systemctl daemon-reload
systemctl restart copyparty
```

### Permission Issues

Ensure the copyparty user has access to shared directories:

```bash theme={null}
# Check ownership
ls -la /path/to/shared/folder

# Fix ownership if needed
chown -R copyparty:copyparty /path/to/shared/folder
```

## Advanced Configuration

### Logging to File

The service creates `/var/log/copyparty/` automatically. Configure logging in `/etc/copyparty.conf`:

```yaml theme={null}
[global]
  q  # Quiet mode (no stdout)
  lo: $LOGS_DIRECTORY/%Y-%m%d.log  # Log to dated files
  # Add .xz extension for compression:
  # lo: $LOGS_DIRECTORY/%Y-%m%d.log.xz
```

### Listening on Ports 80/443

To listen on privileged ports without running as root:

1. Ensure `AmbientCapabilities=CAP_NET_BIND_SERVICE` is in the service file
2. Update configuration:
   ```yaml theme={null}
   [global]
     p: 80,443,3923
   ```
3. Reload and restart:
   ```bash theme={null}
   systemctl daemon-reload
   systemctl restart copyparty
   ```

<Note>
  A reverse proxy (nginx/Apache) is recommended instead of direct port 80/443 access.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Docker Deployment" icon="docker" href="/deployment/docker">
    Run copyparty in a container
  </Card>

  <Card title="Reverse Proxy" icon="server" href="/deployment/reverse-proxy">
    Set up nginx or Apache
  </Card>

  <Card title="Security" icon="shield" href="/deployment/security">
    Harden your installation
  </Card>
</CardGroup>