Getting Started with Famlab¶

Learn to set up your family's private backup infrastructure in 30 minutes

This tutorial will guide you through setting up Famlab from scratch. By the end, you'll have a working SMB backup target that your family's devices can use automatically.

Technical knowledge required

This is an early stage for Famlab and as such, the steps described here require technical knowledge. For example, we are going to issue command in the terminal and use tools such as git. Furthermore, we are assuming you understand basic networking topology and know, at least, whether you have a DHCP server on your network.

What You'll Build¶

You'll create a complete Famlab setup that provides:

3 home backup servers, each handling:
- Network drives for each family member (\\famlab-1\alice, smb://famlab-2/bob, etc.)
- Automatic discovery, devices find the server without configuration
Site autonomy, one server per site (think one server per household¹)
Data replication, each home backup server is replicated on the other two

Before You Start¶

Requirements¶

Proxmox VE host² with some (minimal) resources to spare
Network range, or subnet with appropriate routing, to address the nodes

What You'll Need¶

Basic familiarity with the terminal
Basic familiarity with command-line tools
Ability to connect devices to your network
30 minutes of focused time

Approach¶

To keep things relatively straightforward, we are going to use a simple command-line tool to manage our Famlab deployment. This approach uses direct container management without complex orchestration tools.

Step 1: Initialize your Famlab Deployment¶

Install the Famlab management command¶

git clone https://git.sr.ht/~docbibi/famlab.net
./famlab.net/scripts/install.sh

You can now use the management command famlab to define and work with your own Famlab.

Clean-up after yourself

The management command, once installed, doesn't require the git checkout anymore. You are free to delete your local copy of famlab.net:

rm -rf famlab.net

Create the initial configuration¶

Create a new directory to hold the Famlab configuration:
```
mkdir ~/my-famlab  # Replace with the new directory path
cd ~/my-famlab
```
From now on, all commands will be run from this directory.
Run the initialization command:
```
famlab init famlab-1 famlab-2 famlab-3
```
Name each home backup server uniquely:
- Naming a server famlab-1 would make it accessible on the network at famlab-1.local.
- Fully qualified domain names (FQDN) are also accepted. (If you don't know what that is, no problem, use a simple name as suggested above.)

Step 2: Bootstrap the Deployment¶

Bootstrap the servers with Proxmox VE¶

Run the bootstrap command to provision the containers in Proxmox VE:
```
famlab bootstrap
```
You will need to enter the Proxmox VE host, username, and password.
Check the containers are started and accessible:
```
famlab ping
```

You now have three containers running in Proxmox VE. It is time to transform them to home backup servers!

Overriding the container configuration

The bootstrap command uses default configuration values when creating the containers. The command has optional arguments to override each configuration aspect, for all hosts at once. Take a look at the built-in help: famlab bootstrap --help.

Step 3: Deploy the Servers¶

Configure the containers¶

Deploy the software configuration to all containers:
```
famlab deploy
```
This installs and configures the required services on each container; of note are Samba for SMB file sharing and SSH for inter-server communication.
Test the deployment:
```
famlab test
```
This validates the servers can be reached and their services used.

Your containers are now configured as home backup servers!

Step 4: Manage the Member Accounts¶

Add member accounts¶

famlab user add $(whoami) famlab-1

Each user gets their own SMB share and directory on the specified server.

List existing member accounts¶

famlab user list

Remove member accounts¶

famlab user remove $(whoami)

User removal

Removing a user will delete their SMB account but preserve their data. Use with caution.

Step 5: Set Up Automatic Backups¶

Windows (File History)¶

Open Settings → Update & Security → Backup
Click "Add a drive"
Select your Famlab network drive (\\famlab-1\yourusername)
Turn on "Automatically back up my files"
Click "More options" to customize what gets backed up

macOS (Time Machine)¶

Open System Preferences → Time Machine
Click "Select Backup Disk"
Choose your Famlab network drive (famlab-1/yourusername)
Click "Use Disk" and enter your Famlab credentials
Turn Time Machine "On"

GNU/Linux (Déjà Dup)¶

Open Déjà Dup → Main Menu → Preferences
Set the Storage Location to "Network Server"
Choose your Famlab network drive (smb://username@famlab-1)
Turn automatic backups on ("Back Up Automatically" should be switched on)

GNU/Linux (Pika Backup)¶

Create a new Remote Location Repository
Choose your Famlab network drive (smb://username@famlab-1)

It's a standard target

The Famlab host serves files with the SMB protocol, the most common and well supported file server across operating systems. Virtually any backup software that allows for a "remote location" will work just fine with Famlab.

Step 6: Verify Everything Works¶

Check Backup Status¶

Windows: Settings → Update & Security → Backup → "File History is on"

macOS: System Preferences → Time Machine should show backup progress

GNU/Linux (Déjà Dup): Déjà Dup should show backup progress

GNU/Linux (Pika Backup): Pika Backup should show backup progress

All platforms: Check your network drive to see backup files appearing

Test Recovery¶

Create a test file on your desktop
Wait for backup to complete (trigger manual backup and wait for completion)
Delete the test file
Restore from backup:
- Windows: File History → Browse for files
- macOS: Time Machine → Navigate to file location
- GNU/Linux (Déjà Dup): Déjà Dup → Restore → Navigate to file location
- GNU/Linux (Pika Backup): Pika Backup → […]

What's Next?¶

Congratulations! Your Famlab is now running and protecting your family's data.

Maintenance Tasks¶

This should not be the default

We don't want to play sysadmin with Famlab, that's the whole point. That means we need the happy path to 1) enable monitoring and 2) enable reporting to e-mail and/or a dead-man snitch service. Maybe this could be a fail-safe (in a new section listing alternatives?) as it makes sense to be able to check.

Weekly: Check storage usage and backup status
Monthly: Verify backup integrity by testing recovery
As needed: Add/remove family members

Future Enhancements¶

Once your backup system is running smoothly, see the Future Improvements section for ideas about additional services and enhancements to evaluate.

Getting Help¶

Architecture decisions, Understanding the design
Principles, Core philosophy and approach
Contributing, Help improve Famlab

Your family's digital life is now safely backed up and under your control.

Though of course we could also set up one server per floor, or one per room, etc. What matters is that each family member knows which server they should use, and that all servers can talk to each other. ↩
This guide showcases a single Proxmox VE node hosting the three servers. This undermines the "site autonomy" concept mentioned above, because it's only one physical host in the end. This is an acknowledged trade-off for now. ↩