Host file-social on Raspberry Pi

A tiny computer that runs your website 24/7 from home.

Estimated time: 1-2 hours

What You Need

  • 1. Raspberry Pi with WiFi (Zero W, Zero 2 W, 3, 4, 5, etc.)
  • 2. MicroSD card (8GB or bigger)
  • 3. Power cable (micro USB for Zero W, USB-C for newer)
  • 4. WiFi, with access to router settings
  • 5. Your computer (to set it up)

Step 1: Set Up Your Raspberry Pi

A. Install Raspberry Pi OS

  1. Download Raspberry Pi Imager
  2. Put the microSD card in your computer
  3. Open Imager → Choose OS → Raspberry Pi OS (other) → Raspberry Pi OS Lite (64-bit, newest option)
  4. Choose Storage → your microSD card
  5. Click the gear icon ⚙️ → fill in hostname, username, password, WiFi name & password, enable SSH
  6. Click Write → wait 5 minutes

⚠️ Step 5 is critical — basically every setting matters or it won't set up correctly.

B. Boot it up

  1. Put the microSD card in your Pi
  2. Plug in power
  3. Wait 2 minutes for it to start

C. Test the connection

  1. Open Terminal (Mac) or Command Prompt (Windows)
  2. Type: ssh username@hostname.local (use the username and hostname from step A5)
  3. Type "yes" if it asks about fingerprint
  4. Enter your password
  5. See a command prompt? It works!
  6. Type exit to disconnect

If it doesn't connect, go back to step A and make sure you filled in all the settings correctly.

Step 2: Download file-social

On your computer (not the Pi):

A. Install Node.js

  1. Go to nodejs.org
  2. Click the big green button to download
  3. Open the download and install it

B. Download file-social

  1. Go to this link to download the ZIP
  2. Find it in your Downloads folder
  3. Double-click to unzip it
  4. Drag "file-social-m" to your Desktop

C. Install dependencies

  1. Open Terminal (Mac) or Command Prompt (Windows)
  2. Type: cd then a space, then drag the file-social-m folder into the window, then press Enter
  3. Type: npm install and press Enter
  4. Wait a minute while it downloads stuff

D. Test it locally

  1. Type: npm run dev
  2. Open a browser and go to http://localhost:7650
  3. See your empty stream? It works!
  4. Press Ctrl+C in Terminal/Command Prompt to stop it

Step 3: Connect to Your Pi

This tells file-social where your Pi is and sets up automatic deployment.

Configure once

  1. In Terminal, type: npm run pi:configure
  2. It will ask for info — here's what to put:

Pi username: what you set in Step 1

Pi hostname: something like raspberrypi.local

Port: 8080

This installs software on your Pi, sets up security, and copies your SSH key. Takes about 5 minutes.

Step 4: Deploy Your Site

This copies everything to your Pi and starts it running.

Deploy

  1. In Terminal, type: npm run pi:deploy
  2. Wait about 2 minutes
  3. Done!

Test it:

On your computer, go to: http://raspberrypi.local:8080

(Replace raspberrypi.local with whatever hostname you used)

Step 5: Open a Door in Your Router

Right now only your home network can see it. Let's make it visible to everyone.

A. Find your Pi's address

SSH into your Pi: ssh username@raspberrypi.local

Type: hostname -I → write down the first number (e.g., 192.168.1.50)

B. Log into your router

  1. Go to 192.168.1.1 in a browser (or try 192.168.0.1)
  2. Username and password are usually:
    • admin / admin
    • admin / password
    • (or check the sticker on your router)

C. Add a rule

  1. Find "Port Forwarding" or "Virtual Server"
  2. Click "Add"
  3. Fill in:

    Name: file-social

    External Port: 8080

    Internal IP: (your Pi's 192.168 number)

    Internal Port: 8080

    Protocol: Both

  4. Click Save

Test it:

  1. While SSH'd into your Pi, type: curl v4.ident.me → copy that number
  2. Go to http://YOUR-NUMBER:8080
  3. See your stream? You're on the internet!

Step 6: Get a Real Website Address

Right now people have to type a weird number to visit. Let's give it a real name like yourname.file-social.com

1. Pick a name and sign up

Go here and choose a name.

2. Connect it

Fill out the form:

Domain: yourname.file-social.com

IP Address: (the number from curl v4.ident.me)

Port: 8080

Click "Create Site"

Done!

Go to yourname.file-social.com in any browser. Your stream is live with HTTPS.

Fix Dynamic IP (Optional but Recommended)

Home internet IPs change randomly, breaking your sites. Install the auto-updater to fix this automatically.

Important:

Run this on the machine that is hosting your sites. That may be this device or a different one. SSH into it first if needed.

Without this:

Your sites will randomly go down when your ISP changes your IP. You'll have to manually update each site.

One updater per server:

Install once on each physical server. It automatically updates ALL your sites on that server when the IP changes.

1. After creating your site on yxorp

Sign in and go to any site's details page

2. Copy the installer command

Look for the "Fix Dynamic IP" section with commands for both Linux/Mac and Windows

  • Linux/Mac/Pi: curl -sSL ...
  • Windows: irm ... | iex (run as Admin)

3. Run it on your server

Linux/Mac/Pi: Open Terminal (ssh if needed) on the device and paste the command
Windows: Open PowerShell as Administrator and paste

Note: Install on the machine hosting your sites (could be the same device you're on now). One installation per physical machine.

Done!

ALL your sites on this server will auto-update every 5 minutes. They stay online even when your ISP changes your IP.

Linux/Mac/Pi commands:

• View logs: tail -f ~/.yxorp/updater.log

• Uninstall: ~/.yxorp/updater.sh uninstall

Windows commands:

• View logs: Get-Content ~\.yxorp\updater.log -Tail 20

• Uninstall: Unregister-ScheduledTask -TaskName yxorp-updater -Confirm:$false; Remove-Item -Recurse -Force ~\.yxorp

Step 7: Add Your First Post

Now you can add content to your stream:

Add content

  1. Type: npm run new
  2. Edit the HTML file it creates
  3. Add images to public/data/ if you want
  4. Type: npm run pi:deploy
  5. Refresh your site — your post is live!

Use a code editor to edit HTML files. Cursor is a good option that includes an AI assistant.

Every time: npm run new → edit → npm run pi:deploy

Why This Setup Is Great

It costs almost nothing

Uses about 5 watts. That's $2/year in electricity. No monthly hosting bills.

You own everything

Your photos, your posts, your hardware. No company can shut you down or change the rules.

It's fast enough

Even a Pi Zero W can serve a personal website to dozens of people at once. You're not running a business — you're sharing with friends.

Always running, hands-off

Once deployed, your Pi just runs 24/7. No need to keep a laptop on or babysit anything.

Tips & Troubleshooting

Can't connect to Pi?

Try the IP address instead of raspberrypi.local. Find it in your router's admin page (look for "connected devices").

Deploy failed?

Make sure your Pi is on and connected to WiFi. Try pinging it first.

Site stops working randomly?

Your internet provider probably changed your public IP. Install the auto-updater above to fix this automatically, or SSH into your Pi and run curl v4.ident.me to get the new IP, then update it in yxorp.

Still broken? Reach out to me: cyrus@freshman.dev.

Ready?