Setup Application Locally

Before we deploy to the cloud, let's get the application running on your local machine. You'll fork the repository to create your own copy, customize your unique animal identity, and run the application with Docker Compose.

Prerequisites

Git installed on your machine
A GitHub account (free tier works perfectly)
A terminal or command prompt
Basic familiarity with command line

Step 1: Fork the Repository

Why fork instead of clone?

In this workshop, you'll be making code changes (customizing your animal) and pushing them to GitHub. Forking creates your own copy of the repository that you have full control over.

Fork on GitHub

Go to github.com/lukasredev/furnet
Click the "Fork" button in the top-right corner
Select your GitHub account as the destination
Wait for GitHub to create your fork

You now have your own copy at github.com/YOUR-USERNAME/furnet!

Clone Your Fork

Now clone your fork (not the original repository):

git clone https://github.com/YOUR-USERNAME/furnet
cd furnet

Important: Replace YOUR-USERNAME with your actual GitHub username.

This downloads your forked repository to your local machine and navigates into the project directory.

Step 2: Customize Your Animal Identity

FurNet is a distributed social network where each instance represents a participant with a unique animal identity. Before running the application, let's customize your animal!

Understanding Animal Configuration

Each FurNet instance has an animal identity defined in backend/config.py. This includes:

Required fields: Name, species, and description
Optional fields: Habitat, diet, fun fact, emoji, and color

Workshop Concept: Everyone in the workshop will deploy their own animal, and your instances can connect to each other, forming a distributed social network of animals!

Edit the Configuration File

Open backend/config.py in your favorite text editor (e.g., vim):

vim backend/config.py

Customize Your Animal

Find the AnimalConfig class (around line 27) and customize the values:

class AnimalConfig:
    """
    Animal identity configuration for this FurNet instance.

    WORKSHOP PARTICIPANTS: Edit these values to personalize your animal!
    These are hardcoded and not loaded from environment variables.
    """
    # Animal Identity - Fixed Fields (Required)
    animal_name: str = "Rusty"              # ← Change this to your animal's name
    animal_species: str = "Red Panda"       # ← Change this to your animal species
    animal_description: str = "A curious and playful red panda who loves to explore"  # ← Your description

    # Animal Identity - Optional Fields (customize these too!)
    animal_habitat: Optional[str] = "Bamboo forests of the Himalayas"
    animal_diet: Optional[str] = "Bamboo, fruits, and occasional insects"
    animal_fun_fact: Optional[str] = "Red pandas use their bushy tails as blankets in cold weather"
    animal_emoji: Optional[str] = "🐼"
    animal_color: Optional[str] = "rust-red"

Choose Your Animal

Pick any animal you like! Here are some ideas to get you started:

Land Animals:

Arctic Fox: "A clever arctic fox with brilliant white winter fur"
Elephant: "A gentle giant with remarkable memory and intelligence"
Meerkat: "A social meerkat always on the lookout for adventure"
Sloth: "A relaxed sloth taking life at a comfortable pace"

Ocean Animals:

Sea Otter: "A playful sea otter who floats on their back"
Dolphin: "An intelligent dolphin who loves solving problems"
Octopus: "A mysterious octopus with eight arms of creativity"

Sky Animals:

Owl: "A wise owl active during the quiet night hours"
Hummingbird: "A tiny hummingbird with incredible speed and agility"
Eagle: "A majestic eagle soaring high above the mountains"

Mythical/Fun:

Dragon: "A friendly dragon who collects interesting code snippets"
Penguin: "A tuxedo-wearing penguin who loves cold climates and Linux"

Example Customization:

class AnimalConfig:
    # Animal Identity - Fixed Fields (Required)
    animal_name: str = "Luna"
    animal_species: str = "Arctic Fox"
    animal_description: str = "A clever arctic fox with brilliant white winter fur and keen problem-solving skills"

    # Animal Identity - Optional Fields
    animal_habitat: Optional[str] = "Arctic tundra and snowy mountains"
    animal_diet: Optional[str] = "Small rodents, birds, and berries"
    animal_fun_fact: Optional[str] = "Arctic foxes can survive temperatures as low as -70°C"
    animal_emoji: Optional[str] = "🦊"
    animal_color: Optional[str] = "snow-white"

Save Your Changes

After customizing your animal, save the file and exit your editor:

vim: Press Esc, then type :wq and press Enter
Most editors: Cmd+S (macOS) or Ctrl+S (Windows/Linux)

Commit Your Changes

Now commit your customized animal to your fork:

git add backend/config.py
git commit -m "feat: customize animal identity to [YOUR-ANIMAL-SPECIES]"
git push origin main

Why commit now?

When you set up GitHub Actions in the next section, it will automatically build your customized animal into Docker images. This way, your deployed instance will have your unique animal identity!

Step 3: Install Docker

Docker packages your application with all its dependencies, making it easy to run consistently across different environments.

macOS

Option A: Docker Desktop (Recommended)

Download Docker Desktop from docker.com/products/docker-desktop
Open the downloaded .dmg file and drag Docker to your Applications folder
Launch Docker Desktop from Applications
Wait for Docker to start (the whale icon in the menu bar will be steady)

Option B: Homebrew

brew install --cask docker

Windows

Download Docker Desktop from docker.com/products/docker-desktop
Run the installer
Follow the installation wizard
Restart your computer if prompted
Launch Docker Desktop

Note: Docker Desktop on Windows requires WSL 2. The installer will guide you through enabling it if needed.

Linux

Ubuntu/Debian:

# Update package index
sudo apt-get update

# Install dependencies
sudo apt-get install ca-certificates curl gnupg

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Set up repository
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify Docker Installation

Check that Docker is installed correctly:

docker --version

You should see output like: Docker version 24.0.0, build abc1234

Step 4: Install Docker Compose

Docker Compose allows you to define and run multi-container applications.

macOS and Windows

If you installed Docker Desktop, Docker Compose is already included. Verify with:

docker compose version

Linux

Docker Compose is included with recent Docker installations as a plugin. If you followed the installation steps above, you should already have it.

Verify with:

docker compose version

If you need to install it separately:

sudo apt-get install docker-compose-plugin

Step 5: Run the Application

Now that everything is installed, start the application:

docker compose up --build

What this command does:

docker compose up: Starts all services defined in docker-compose.yml
--build: Rebuilds the Docker images before starting (ensures you have the latest code)

First run: This will take a few minutes as Docker downloads base images and builds your containers.

What You'll See

Docker Compose will output logs from all services. You should see something like:

[+] Building 45.2s
[+] Running 2/2
 ✔ Container furnet-backend-1   Started
 ✔ Container furnet-frontend-1  Started
Attaching to backend-1, frontend-1
backend-1  | Server running on http://0.0.0.0:8000
frontend-1 | Server running on http://0.0.0.0:8080

Step 6: Access the Application

Once the containers are running, open your browser and navigate to:

Frontend: http://localhost:8080
Backend API: http://localhost:8080/api

You should see the application's interface in your browser.

Verify Your Animal Identity

Check that your customized animal appears correctly:

Visit the frontend at http://localhost:8080
- You should see your animal's name, species, and description
Check the API directly at http://localhost:8080/api/me
- This endpoint returns your animal's full profile as JSON
- Verify all your customized fields appear correctly

Example API response:

{
  "id": "localhost:luna",
  "name": "Luna",
  "species": "Arctic Fox",
  "description": "A clever arctic fox with brilliant white winter fur and keen problem-solving skills",
  "instance_url": "http://localhost:8080/api",
  "habitat": "Arctic tundra and snowy mountains",
  "diet": "Small rodents, birds, and berries",
  "fun_fact": "Arctic foxes can survive temperatures as low as -70°C",
  "emoji": "🦊",
  "color": "snow-white"
}

Troubleshooting: If you still see "Rusty the Red Panda", you may need to rebuild:

# Stop the containers
docker compose down

# Rebuild and restart
docker compose up --build

Common Commands

Stop the application

Press Ctrl+C in the terminal where Docker Compose is running, or use:

docker compose down

Restart with fresh build

If you make changes to the code:

docker compose up --build

View running containers

docker compose ps

Troubleshooting

Port already in use

If you see an error like "port is already allocated":

# Find what's using the port (macOS/Linux)
lsof -i :8080

# Windows
netstat -ano | findstr :8080

Either stop the conflicting process or modify the port in docker-compose.yml.

Permission denied (Linux)

If you get permission errors:

# Add your user to the docker group
sudo usermod -aG docker $USER

# Log out and back in for changes to take effect

Docker daemon not running

Make sure Docker Desktop is running (macOS/Windows) or start the Docker service (Linux):

sudo systemctl start docker

What You've Accomplished

Congratulations! You've:

✓ Forked the FurNet repository to your GitHub account
✓ Customized your unique animal identity
✓ Committed your changes to your fork
✓ Installed Docker and Docker Compose
✓ Run the application locally
✓ Verified your animal appears correctly

Next Steps

Now that your application runs locally with your customized animal, continue to Step 3: Automate Builds with GitHub Actions to set up continuous integration that automatically builds Docker images every time you push code.

Step 2 - Setup Application Locally - VIScon 2025 Workshop

Setup Application Locally

Prerequisites

Step 1: Fork the Repository

Fork on GitHub

Clone Your Fork

Step 2: Customize Your Animal Identity

Understanding Animal Configuration

Edit the Configuration File

Customize Your Animal

Choose Your Animal

Save Your Changes

Commit Your Changes

Step 3: Install Docker

macOS

Windows

Linux

Verify Docker Installation

Step 4: Install Docker Compose

macOS and Windows

Linux

Step 5: Run the Application

What You'll See

Step 6: Access the Application

Verify Your Animal Identity

Common Commands

Stop the application

Restart with fresh build

View running containers

Troubleshooting

Port already in use

Permission denied (Linux)

Docker daemon not running

What You've Accomplished

Next Steps