Installation guide

About twenty minutes, most of it waiting for downloads. You don't need any technical experience: an installer asks a few questions, recommends an answer for each, and does the rest.

The server is published with the public release. Until then the download and the command below are placeholders, and this is how they will work. To be told when it's out, write to [email protected].

Home Stream runs on a Raspberry Pi, which is small, quiet and cheap to leave on, or on a Mac with Apple silicon.

On a Raspberry Pi

What you need

About the drive

  1. Prepare the SD card

    On your computer, download Raspberry Pi Imager, the Raspberry Pi Foundation's free app, and open it.

    • Choose your Raspberry Pi model.
    • For the operating system, choose Raspberry Pi OS (64-bit). The Lite version is all Home Stream needs.
    • Choose your SD card.
    • When Imager offers to customise the settings, say yes, and set:
      • Hostname: homestream
      • Username and password: your choice. Write them down.
      • Wi-Fi: only if you aren't using a cable.
      • Services: turn on SSH, with password authentication.

    Then write the card. The Raspberry Pi Foundation's own getting started guide walks through every screen if you'd like more detail.

  2. Start the Pi

    Put the card in the Pi, plug in the USB drive and the network cable, and connect the power. Give it two or three minutes the first time.

  3. Connect to it from your computer

    On a Mac, open Terminal (in Applications → Utilities). On Windows, open PowerShell from the Start menu. Type this, with the username you chose, and press Return:

    ssh [email protected]

    The first time, it asks whether you're sure you want to connect: type yes. Then enter your password. Nothing appears as you type it; that's normal.

    If homestream.local doesn't work, use the Pi's IP address instead. An IP address is four numbers separated by dots, such as 192.168.1.42. With it, the command becomes: 
    ssh [email protected]
    To find your Pi's IP address, any one of these works:
    • Your router. Its app or its web page lists the devices connected to your network. Look for homestream; the address is beside it.
    • A screen and keyboard on the Pi. Sign in on the Pi itself and type hostname -I. The first set of four numbers is its address.
    • A network scanner app on your phone, such as Fing, which lists every device on your Wi-Fi with its address.
    Use the IP address anywhere this guide says homestream.local, including in your browser: http://192.168.1.42:8080. The Raspberry Pi Foundation's guide to connecting remotely has more ways to find it.

  4. Run the installer

    Paste this line and press Return:

    bash -c "$(curl -fsSL https://openhomestream.com/install.sh)"

    It checks the Pi, then asks a few questions. Press Return to accept the recommended answer shown in brackets:

    • Docker, which runs the server, is installed if it's missing. It asks first, and may ask for your password.
    • Your drive is found and, if it isn't ready to use, the installer offers to mount it: make it available now and after every restart, even when nobody is signed in at the Pi. Say yes. Nothing on the drive is changed. If the drive is formatted for a Mac, it says so and explains what to do.
    • Where your library is, from a list of the drives it finds. The drive doesn't need folders for films, TV or music yet: you can make them later in the browser, with New Folder.
    • Where the server keeps its own data, its database and the artwork it downloads. It recommends a homestream-data folder on your library drive: press Return to accept. It warns you if you choose the SD card.
    • Letting the apps find the server by name, so nobody types an address on a television.
    • Automatic updates, at a quiet hour you can change later in Settings.

  5. Open Home Stream

    When it finishes, the installer shows an address, such as http://homestream.local:8080, and a setup code. If that address doesn't open, use the Pi's IP address instead: http://192.168.1.42:8080, with your Pi's numbers. Open the address in a browser on any computer in the house, enter the code, and choose a username and password for the administrator account.

    The administrator account looks after the server and isn't for watching. You'll invite yourself next, like everyone else.

  6. Add your TMDb key

    Posters and details for films and television come from TMDb, which needs a free key of your own. Getting started shows how to get one in about five minutes and where to paste it.

You can close Terminal now. The Pi carries on by itself, and comes back on its own after a power cut.

Mounting the drive yourself

The installer mounts your drive for you, so this is only for anyone who'd rather do it by hand, or whose drive the installer couldn't mount. Connected to the Pi, as in step 3:

  1. Find the drive. Plug it in and type: 
    lsblk -o NAME,SIZE,FSTYPE,LABEL,MOUNTPOINT
    Your drive is the one with the size you expect, usually sda, with a partition such as sda1 listed under it. Note its FSTYPE: exfat, ntfs or ext4.
  2. Find its UUID, the drive's permanent name: 
    sudo blkid /dev/sda1
  3. Make a folder for it: 
    sudo mkdir -p /mnt/media
  4. Tell the Pi to mount it at every start. Open the list of drives with sudo nano /etc/fstab and add one line at the end, using your UUID. For an exFAT drive: 
    UUID=your-uuid  /mnt/media  exfat  defaults,nofail,uid=1000,gid=1000,umask=002  0  2
    For NTFS, write ntfs3 in place of exfat. For ext4: 
    UUID=your-uuid  /mnt/media  ext4  defaults,nofail  0  2
    Save with Ctrl-O and Return, then leave with Ctrl-X. nofail lets the Pi start normally even when the drive is unplugged.
  5. Mount it now, and check you can see your files: 
    sudo systemctl daemon-reload
sudo mount -a
ls /mnt/media

Then run the installer and choose /mnt/media when it asks where your library is.

On a Mac

Any Mac with Apple silicon (M1 or later) can run the server. It needs to stay on and signed in while people are watching, so a Mac that's always on, such as a Mac mini, suits it best.

  1. Open Terminal and run the installer

    Open Terminal (Applications → Utilities), paste this line and press Return:

    bash -c "$(curl -fsSL https://openhomestream.com/install.sh)"

  2. Let it set up Docker Desktop

    The server runs in Docker Desktop, Docker's free app for the Mac. If it isn't installed, the installer installs it, or opens its download page, and waits while you open it once and accept its terms. In Docker Desktop's settings, turn on Start Docker Desktop when you sign in, so the server comes back after a restart.

  3. Answer its questions

    Where your library is (it lists your drives and your Movies folder), where to keep the server's data, and whether to install updates automatically. Press Return for each recommended answer.

  4. Finish in the browser

    The installer opens Home Stream in your browser and shows the setup code. Enter it and choose the administrator's username and password.

    On a Mac, the apps can't find the server by name yet, so type its address into each app once. The installer shows it.

  5. Add your TMDb key

    For posters and details. Getting started shows how.

Getting your media onto it

Updating, and changing an answer

With automatic updates on, there's nothing to do: new versions install themselves at the hour you choose under Settings → Server → Software Update. To update straight away, or to change an answer such as where your library is, run the installer again. It sees what's there and offers to update, change the answers, or leave everything as it is. Your library, accounts and history are never touched by an update.

If something goes wrong

For the technically minded

The installer writes two files, compose.yaml and .env, into ~/homestream, then runs docker compose up -d. Everything it sets is listed under Set when installing, and you can edit .env by hand and run docker compose up -d again. The installer itself is a readable shell script: install.sh.

Next: Getting started, to add your library and invite the household.