🚀 Tutorial Website · Self-Hosted File Browser

Deploy File Browser with an auto-detecting Linux script.

This guide explains what the script does, what it installs, how it detects your server, how the Docker image is built, and how users can run it with Docker Compose.

Start Setup Copy Script

$ ./setup-filebrowser.sh

[OK] Linux detected

[OK] CPU architecture detected

[OK] Missing packages installed only if needed

[OK] Docker or Podman prepared

[BUILD] my-filebrowser image ready

What the script does

The script automates the boring parts: OS detection, CPU architecture detection, package checking, container engine setup, File Browser download, Dockerfile generation, and image build.

Linux detection

Detects Debian, Ubuntu, Fedora, RHEL-like, Arch, openSUSE, Alpine, and their package managers.

CPU detection

Supports AMD64, ARM64, ARMv7, ARMv6, 386, s390x, and ppc64le.

Package-aware

Checks required packages first and installs only what is missing.

Docker first

Uses Docker when available and tries to install/start it when missing.

Podman fallback

Can fall back to Podman if Docker is not usable.

Local image build

Builds my-filebrowser, then Compose runs that image.

Setup flow

Users only need to save the script, run it, then start Docker Compose.

Create folder

Use a clean project folder for the script, compose file, files, and database.

Run script

The script scans the system, installs missing tools, and builds the image.

Start Compose

Docker Compose starts File Browser with persistent folders and safer defaults.

Project folder

mkdir -p ~/filebrowser-autoforge
cd ~/filebrowser-autoforge

Full setup script

Save this as setup-filebrowser.sh. This is the actual script users should run before using Docker Compose.

setup-filebrowser.sh

#!/usr/bin/env bash
set -Eeuo pipefail

# File Browser AutoForge
# Detects Linux + CPU architecture, installs only missing packages,
# prepares Docker or Podman, downloads the correct File Browser binary,
# and builds a local image for Docker Compose.

IMAGE_NAME="${FILEBROWSER_IMAGE:-my-filebrowser}"
REPO="${FILEBROWSER_REPO:-filebrowser/filebrowser}"
ALLOW_PODMAN_FALLBACK="${ALLOW_PODMAN_FALLBACK:-1}"
WORK_DIR="$(mktemp -d)"

cleanup(){ rm -rf "$WORK_DIR"; }
trap cleanup EXIT
trap 'echo "[x] Failed at line $LINENO: $BASH_COMMAND" >&2' ERR

if [[ -t 1 ]]; then
  RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'
  CYAN='\033[0;36m'; BOLD='\033[1m'; RESET='\033[0m'
else
  RED=''; GREEN=''; YELLOW=''; CYAN=''; BOLD=''; RESET=''
fi

log(){ echo -e "${CYAN}[*]${RESET} $*"; }
ok(){ echo -e "${GREEN}[OK]${RESET} $*"; }
warn(){ echo -e "${YELLOW}[!]${RESET} $*"; }
die(){ echo -e "${RED}[x]${RESET} $*" >&2; exit 1; }

SUDO=()
ENGINE=()
ENGINE_NAME=""

setup_privilege(){
  if [[ "$EUID" -eq 0 ]]; then
    SUDO=()
    ok "Running as root."
  else
    command -v sudo >/dev/null 2>&1 || die "sudo missing. Run as root or install sudo."
    sudo -v
    SUDO=(sudo)
    ok "Using sudo."
  fi
}

as_root(){ "${SUDO[@]}" "$@"; }

detect_os(){
  OS_ID="unknown"
  OS_PRETTY="Unknown Linux"
  OS_VERSION_CODENAME=""

  if [[ -r /etc/os-release ]]; then
    # shellcheck disable=SC1091
    . /etc/os-release
    OS_ID="${ID:-unknown}"
    OS_PRETTY="${PRETTY_NAME:-$OS_ID}"
    OS_VERSION_CODENAME="${VERSION_CODENAME:-${UBUNTU_CODENAME:-}}"
  fi

  ok "Linux detected: $OS_PRETTY"
}

detect_pkg_manager(){
  if command -v apt-get >/dev/null 2>&1; then PM="apt"
  elif command -v dnf >/dev/null 2>&1; then PM="dnf"
  elif command -v yum >/dev/null 2>&1; then PM="yum"
  elif command -v pacman >/dev/null 2>&1; then PM="pacman"
  elif command -v zypper >/dev/null 2>&1; then PM="zypper"
  elif command -v apk >/dev/null 2>&1; then PM="apk"
  else die "No supported package manager found."; fi

  ok "Package manager: $PM"
}

pkg_update(){
  case "$PM" in
    apt) as_root apt-get update -qq ;;
    pacman) as_root pacman -Sy --noconfirm --quiet ;;
    zypper) as_root zypper refresh -q ;;
    apk) as_root apk update >/dev/null ;;
    *) true ;;
  esac
}

pkg_install(){
  case "$PM" in
    apt) as_root apt-get install -y -qq "$@" ;;
    dnf) as_root dnf install -y -q "$@" ;;
    yum) as_root yum install -y -q "$@" ;;
    pacman) as_root pacman -S --needed --noconfirm --quiet "$@" ;;
    zypper) as_root zypper install -y -q "$@" ;;
    apk) as_root apk add --quiet "$@" ;;
  esac
}

is_pkg_installed(){
  local pkg="$1"
  case "$PM" in
    apt) dpkg-query -W -f='${Status}' "$pkg" 2>/dev/null | grep -q "install ok installed" ;;
    dnf|yum|zypper) rpm -q "$pkg" >/dev/null 2>&1 ;;
    pacman) pacman -Q "$pkg" >/dev/null 2>&1 ;;
    apk) apk info -e "$pkg" >/dev/null 2>&1 ;;
    *) return 1 ;;
  esac
}

install_missing_packages(){
  local missing=()
  for pkg in "$@"; do
    if is_pkg_installed "$pkg"; then
      ok "$pkg already installed."
    else
      missing+=("$pkg")
    fi
  done

  if [[ "${#missing[@]}" -gt 0 ]]; then
    log "Installing missing packages: ${missing[*]}"
    pkg_install "${missing[@]}"
  else
    ok "All required packages already installed."
  fi
}

detect_arch(){
  MACHINE="$(uname -m)"

  case "$MACHINE" in
    x86_64|amd64) ARCH="linux-amd64"; JQ_ARCH="amd64"; DOCKER_PLATFORM="linux/amd64" ;;
    aarch64|arm64) ARCH="linux-arm64"; JQ_ARCH="arm64"; DOCKER_PLATFORM="linux/arm64" ;;
    armv7l|armv7*) ARCH="linux-armv7"; JQ_ARCH="armhf"; DOCKER_PLATFORM="linux/arm/v7" ;;
    armv6l) ARCH="linux-armv6"; JQ_ARCH="armel"; DOCKER_PLATFORM="linux/arm/v6" ;;
    i386|i486|i586|i686) ARCH="linux-386"; JQ_ARCH="i386"; DOCKER_PLATFORM="linux/386" ;;
    s390x) ARCH="linux-s390x"; JQ_ARCH="s390x"; DOCKER_PLATFORM="linux/s390x" ;;
    ppc64le) ARCH="linux-ppc64le"; JQ_ARCH="ppc64le"; DOCKER_PLATFORM="linux/ppc64le" ;;
    *) die "Unsupported CPU architecture: $MACHINE" ;;
  esac

  CPU_THREADS="$(getconf _NPROCESSORS_ONLN 2>/dev/null || echo unknown)"
  CPU_MODEL="Unknown CPU"

  if command -v lscpu >/dev/null 2>&1; then
    CPU_MODEL="$(lscpu | awk -F: '/Model name|BIOS Model name|Processor/ {
      gsub(/^[ \t]+/, "", $2)
      if ($2 != "") { print $2; exit }
    }')"
    CPU_MODEL="${CPU_MODEL:-Unknown CPU}"
  fi

  ok "CPU: $CPU_MODEL"
  ok "Threads: $CPU_THREADS"
  ok "Architecture: $MACHINE -> $ARCH"
  ok "Container platform: $DOCKER_PLATFORM"
}

install_base_packages(){
  log "Checking required base packages..."

  case "$PM" in
    apt) pkg_update; install_missing_packages ca-certificates curl tar gzip gnupg ;;
    dnf|yum) install_missing_packages ca-certificates curl tar gzip ;;
    pacman) pkg_update; install_missing_packages ca-certificates curl tar gzip ;;
    zypper) pkg_update; install_missing_packages ca-certificates curl tar gzip ;;
    apk) pkg_update; install_missing_packages ca-certificates curl tar gzip ;;
  esac

  ok "Base package check complete."
}

install_jq(){
  if command -v jq >/dev/null 2>&1; then
    ok "jq already installed."
    return
  fi

  if is_pkg_installed jq; then
    ok "jq already installed."
    return
  fi

  log "Installing jq..."

  if pkg_install jq; then
    ok "jq installed."
    return
  fi

  warn "Package install failed. Trying static jq binary..."
  JQ_URL="https://github.com/jqlang/jq/releases/latest/download/jq-linux-${JQ_ARCH}"

  curl -fsSL "$JQ_URL" -o "$WORK_DIR/jq"
  chmod +x "$WORK_DIR/jq"
  as_root install -m 0755 "$WORK_DIR/jq" /usr/local/bin/jq

  command -v jq >/dev/null 2>&1 || die "jq installation failed."
  ok "jq installed from static binary."
}

start_docker_service(){
  if command -v systemctl >/dev/null 2>&1 && [[ -d /run/systemd/system ]]; then
    as_root systemctl enable --now docker || warn "Could not start Docker with systemctl."
  elif command -v rc-update >/dev/null 2>&1 && command -v rc-service >/dev/null 2>&1; then
    as_root rc-update add docker default || true
    as_root rc-service docker start || warn "Could not start Docker with OpenRC."
  elif command -v service >/dev/null 2>&1; then
    as_root service docker start || warn "Could not start Docker with service."
  else
    warn "No supported init system found. Start Docker manually if required."
  fi
}

set_container_engine(){
  if command -v docker >/dev/null 2>&1; then
    if docker info >/dev/null 2>&1; then
      ENGINE=(docker)
      ENGINE_NAME="docker"
      ok "Using Docker."
      return 0
    fi

    if [[ ${#SUDO[@]} -gt 0 ]] && "${SUDO[@]}" docker info >/dev/null 2>&1; then
      ENGINE=("${SUDO[@]}" docker)
      ENGINE_NAME="sudo docker"
      ok "Using Docker with sudo."
      return 0
    fi
  fi

  if [[ "$ALLOW_PODMAN_FALLBACK" == "1" ]] && command -v podman >/dev/null 2>&1; then
    ENGINE=(podman)
    ENGINE_NAME="podman"
    ok "Using Podman fallback."
    return 0
  fi

  return 1
}

install_docker_distro(){
  log "Trying distro Docker package..."

  case "$PM" in
    apt) pkg_update; install_missing_packages docker.io || pkg_install docker.io || pkg_install docker ;;
    dnf) install_missing_packages docker || pkg_install docker || pkg_install moby-engine ;;
    yum) install_missing_packages docker || pkg_install docker || pkg_install moby-engine ;;
    pacman) pkg_update; install_missing_packages docker ;;
    zypper) pkg_update; install_missing_packages docker || pkg_install docker || pkg_install docker-ce ;;
    apk) pkg_update; install_missing_packages docker ;;
  esac
}

install_podman(){
  log "Installing Podman fallback..."

  case "$PM" in
    apt) pkg_update; install_missing_packages podman ;;
    dnf|yum) install_missing_packages podman ;;
    pacman) pkg_update; install_missing_packages podman ;;
    zypper) pkg_update; install_missing_packages podman ;;
    apk) pkg_update; install_missing_packages podman ;;
  esac

  command -v podman >/dev/null 2>&1 || return 1
}

install_container_engine(){
  if set_container_engine; then return; fi

  log "Installing Docker..."
  install_docker_distro || warn "Docker package installation failed."

  start_docker_service
  sleep 2

  if set_container_engine; then return; fi

  if [[ "$ALLOW_PODMAN_FALLBACK" == "1" ]]; then
    warn "Docker is not usable. Trying Podman fallback..."
    install_podman || die "Could not install Docker or Podman."
    set_container_engine || die "No working container engine found."
    return
  fi

  die "Docker installed but is not usable. Start Docker manually."
}

fetch_latest_release(){
  log "Fetching latest File Browser release..."

  RELEASE_JSON="$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest")"
  LATEST="$(printf '%s' "$RELEASE_JSON" | jq -r '.tag_name // empty')"

  [[ -n "$LATEST" ]] || die "Could not detect latest release."

  TARBALL="${ARCH}-filebrowser.tar.gz"

  ASSET_URL="$(printf '%s' "$RELEASE_JSON" | jq -r --arg name "$TARBALL" '
    .assets[]?
    | select(.name == $name)
    | .browser_download_url
  ' | head -n1)"

  [[ -n "$ASSET_URL" ]] || die "No release asset found for: $TARBALL"

  ok "Latest version: $LATEST"
  ok "Asset: $TARBALL"
}

download_binary(){
  log "Downloading File Browser binary..."

  curl -fsSL "$ASSET_URL" -o "$WORK_DIR/$TARBALL"
  tar -xzf "$WORK_DIR/$TARBALL" -C "$WORK_DIR"

  [[ -f "$WORK_DIR/filebrowser" ]] || die "filebrowser binary not found after extraction."

  chmod +x "$WORK_DIR/filebrowser"
  ok "Binary downloaded and extracted."
}

write_dockerfile(){
  log "Writing Dockerfile..."

  cat > "$WORK_DIR/Dockerfile" <<'DOCKERFILE'
FROM alpine:3.20

RUN apk add --no-cache ca-certificates tzdata wget \
    && addgroup -S filebrowser \
    && adduser -S -D -H -h /srv -s /sbin/nologin -G filebrowser filebrowser \
    && mkdir -p /srv /database \
    && chown -R filebrowser:filebrowser /srv /database

COPY filebrowser /usr/local/bin/filebrowser

WORKDIR /srv

EXPOSE 80

USER filebrowser

ENTRYPOINT ["filebrowser", "--address", "0.0.0.0", "--port", "80", "--root", "/srv", "--database", "/database/filebrowser.db"]
DOCKERFILE

  ok "Dockerfile written."
}

build_image(){
  log "Building image: ${BOLD}${IMAGE_NAME}${RESET}"

  "${ENGINE[@]}" build \
    --platform "$DOCKER_PLATFORM" \
    -t "$IMAGE_NAME" \
    "$WORK_DIR"

  ok "Image built successfully: $IMAGE_NAME"
}

print_summary(){
  echo ""
  echo -e "${BOLD}----------------------------------------${RESET}"
  echo -e "${GREEN} File Browser image is ready.${RESET}"
  echo -e "${BOLD}----------------------------------------${RESET}"
  echo ""
  echo "Detected:"
  echo "  Linux:    $OS_PRETTY"
  echo "  CPU arch: $MACHINE"
  echo "  Platform: $DOCKER_PLATFORM"
  echo "  Engine:   $ENGINE_NAME"
  echo "  Image:    $IMAGE_NAME"
  echo ""
  echo "Next commands:"
  echo "  mkdir -p files database"
  echo "  docker compose up -d"
  echo ""
  echo "Open:"
  echo "  http://SERVER-IP:8080"
  echo ""
}

main(){
  detect_arch
  detect_os
  detect_pkg_manager
  setup_privilege
  install_base_packages
  install_jq
  install_container_engine
  fetch_latest_release
  download_binary
  write_dockerfile
  build_image
  print_summary
}

main "$@"

Run it

chmod +x setup-filebrowser.sh
./setup-filebrowser.sh

Full Docker Compose setup

Save this as docker-compose.yml after the image is built. It includes persistent storage, restart policy, healthcheck, log rotation, and security hardening.

docker-compose.yml

services:
  filebrowser:
    image: ${FILEBROWSER_IMAGE:-my-filebrowser}
    container_name: ${FILEBROWSER_CONTAINER:-filebrowser}

    restart: unless-stopped
    init: true

    ports:
      - "${FILEBROWSER_PORT:-8080}:80"

    volumes:
      - type: bind
        source: ./files
        target: /srv
      - type: bind
        source: ./database
        target: /database

    security_opt:
      - no-new-privileges:true

    cap_drop:
      - ALL

    cap_add:
      - NET_BIND_SERVICE

    pids_limit: 256
    stop_grace_period: 20s

    healthcheck:
      test: ["CMD-SHELL", "wget -q --spider http://127.0.0.1:80/ || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 20s

    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

    networks:
      - filebrowser_net

networks:
  filebrowser_net:
    name: filebrowser_net
    driver: bridge

Start File Browser

mkdir -p files database
docker compose up -d
docker compose ps
docker compose logs -f filebrowser

Access and firewall

Open File Browser from your browser after Compose starts.

URL

Open http://SERVER-IP:8080.

Login

Default login is usually admin / admin. Change it immediately.

UFW firewall

sudo ufw allow 8080/tcp
sudo ufw reload
sudo ufw status

Cloud VPS note: also allow TCP port 8080 in Oracle/AWS/Azure/Google/Hetzner security rules.

Troubleshooting

Common problems and quick fixes.

Docker Compose says image not found

Run ./setup-filebrowser.sh first. It builds the local image named my-filebrowser.

Port 8080 does not open

Check docker compose ps, logs, Linux firewall, and VPS security rules.

Permission problem

Create folders first with mkdir -p files database. For testing only, use chmod -R 777 files database.

Need another port

Create a .env file with FILEBROWSER_PORT=8090, then restart Compose.