Install the server

The server gets detections from your BirdNET device or BirdWeather station, renders the pictures, and sends them to your frames. It also runs the Featherframe webapp, where you add frames and change settings.

You can use Featherframe Cloud, install it on your BirdNET device, or run it in Docker on a NAS or home server.

Featherframe Cloud

Featherframe Cloud runs the server for you, at cloud.featherframe.app. A ready-made frame is set up on it from your phone: see Set up your frame. For a frame you built, join the waitlist at featherframe.app, and confirm your address from the email it sends. You'll get an invitation by email. Then install the firmware, and add the frame.

On your BirdNET device

You can install Featherframe alongside BirdNET-Pi or BirdNET-Go on a Raspberry Pi or home server.

1. SSH into your BirdNET device, then run:

   git clone https://github.com/wr/featherframe ~/featherframe
   cd ~/featherframe/server
   ./install.sh

2. When it finishes, the installer prints the address of your Featherframe webapp, for example http://birdnet.local:8181. Open it.

3. Go to Detection source and connect your source.

4. Install the firmware, and connect the frame to your server. Leave its address blank.

5. Add the frame.

Note

Featherframe uses port 8181, so it doesn't clash with BirdNET-Go on 8080.

What the installer does

• Installs Featherframe and its Python packages.
• Downloads the illustrations Featherframe uses from Audubon's and Gould's books (about 7 GB).
• Starts Featherframe now and each time the device starts, at low priority so BirdNET runs first.

Installer options

Option	What it does
--port 9000	Uses port 9000 instead of 8181.
--skip-plates	Doesn't download the illustrations. Run ./install.sh again later to download them.
--all-plates	Downloads all 435 of Audubon's illustrations (about 2.9 GB), not only the ones Featherframe uses.
--source birdnet-go	Sets the detection source: birdnet-pi (the default) or birdnet-go. Only on the run that has it: later runs keep what the webapp set.
--no-service	Doesn't start Featherframe automatically.
--check	Lists what the installer would change, and changes nothing.

Update Featherframe

cd ~/featherframe
git pull
cd server
./install.sh

This keeps your settings, frames, AI illustrations, and port. It downloads only the new illustrations it needs, then restarts Featherframe.

Back up your AI illustrations

Important

AI illustrations are stored only on your BirdNET device, and each one cost money to make. Back them up before you move or reinstall the server.

To back them up:

1. In your Featherframe webapp, go to Generated illustrations.
2. Click Download a backup.

To restore them, click Restore from a backup… on the new server. It doesn't replace an illustration that is newer than the one in the backup.

Add a password

Warning

The Featherframe webapp has no password by default. Use it only on your home network. Don't make it reachable from the internet.

To add a password, go to Settings → General and click Set password. You'll then sign in with your email and password. Frames don't need the password.

If you forget the password, run this command, then restart Featherframe:

~/featherframe/server/.venv/bin/python -m featherframe --clear-password

If you changed Featherframe's data folder, run the command with the same FEATHERFRAME_* settings as the service.

On a NAS or home server

Featherframe runs in Docker on any Linux machine on the same network as your BirdNET device and frames.

1. Make a folder for Featherframe, and download docker-compose.yml into it.

2. In docker-compose.yml, set TZ to your time zone, for example Europe/London.

3. In that folder, run:

   docker compose up -d

4. Open http://<your-server>:8181.

5. Go to Detection source and connect your source.

6. Install the firmware, and connect the frame to your server. Leave its address blank.

7. Add the frame.

Settings, frames, and AI illustrations are kept in the data folder beside docker-compose.yml. The illustrations aren't downloaded up front: each one is fetched the first time it's needed.

Frames find the server by themselves

The container uses host networking, so a frame set to Self-hosted finds the server with no address to type in. Host networking needs Linux, which most NASes run.

If you can't use host networking, for example on Docker Desktop:

1. In docker-compose.yml, delete network_mode: host, and uncomment ports and FEATHERFRAME_NO_MDNS.
2. On each frame, choose Self-hosted under Server, and enter http://<your-server>:8181. See Connect to your own server.

Update the container

docker compose pull
docker compose up -d

Clear the password

docker compose exec featherframe python -m featherframe --clear-password
docker compose restart

Troubleshooting

The frame doesn't find your server

• If the frame shows a setup code, it's looking for Featherframe Cloud. Connect it to your server.
• Otherwise, open http://<your-server>/api/status and find mdns.advertised. If it's false, read mdns.error beside it. disabled means the server was started with this turned off. zeroconf not installed means run ./install.sh again.
• If your network blocks this kind of announcement, enter the server's address in the frame. See Connect to your own server.

The frame shows pictures from a different server

If a frame can't reach its own server, it uses any other Featherframe server on your network, like a test copy on a laptop.

1. Stop the other server. The frame returns to its own server.
2. Start any test server with FEATHERFRAME_NO_MDNS=1 so frames don't find it.

Illustrations are missing

Run the download again. It only downloads what's missing.

~/featherframe/server/.venv/bin/python ~/featherframe/server/scripts/fetch_plates.py

Local database: Not reachable

• Check the file's location. The default is ~/BirdNET-Pi/scripts/birds.db.
• The file must be on the same device as Featherframe. If BirdNET-Pi runs on another device, use BirdNET-Pi notifications instead.
• Check that the file exists and Featherframe can read it: ls -l ~/BirdNET-Pi/scripts/birds.db

Next: Flash the frame.