Skip to main content

​
Overview

This guide walks you through setting up PhotoFlow on your local machine. This setup is ideal for:
  • Development and testing
  • Single-user installations
  • Evaluating PhotoFlow before production deployment
  • Learning how PhotoFlow works
For production multi-PC deployments, see the Docker deployment guide or network setup guide.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 20+ installed (check requirements)
  • PostgreSQL 15+ installed and running
  • Git (optional, for cloning the repository)
  • Terminal/Command Prompt access

​
Installation Steps

1

Clone the Repository

Download PhotoFlow from GitHub:
git clone https://github.com/DomenicWalther/PhotoFlow.git
cd PhotoFlow
If you don’t have Git installed:
  1. Go to github.com/DomenicWalther/PhotoFlow
  2. Click the green “Code” button
  3. Select “Download ZIP”
  4. Extract the ZIP file
  5. Open terminal in the extracted folder
2

Install Dependencies

Install all required npm packages:
npm install
This installs:
  • SvelteKit - Web framework
  • Prisma - Database ORM
  • Socket.io - Real-time communication
  • TailwindCSS - Styling framework
  • All other dependencies defined in package.json
The installation may take a few minutes depending on your internet connection.
3

Configure Environment Variables

Create a .env file in the project root directory:
touch .env
Add your database configuration:
.env
# Database URL for PostgreSQL
DATABASE_URL="postgresql://photoflow:photoflow_password@localhost:5432/photoflow"
Connection string format:
postgresql://[user]:[password]@[host]:[port]/[database]
Replace with your PostgreSQL credentials:
  • photoflow - your database username
  • photoflow_password - your database password
  • localhost - database host (use localhost for local setup)
  • 5432 - PostgreSQL port (default is 5432)
  • photoflow - database name
Never commit the .env file to version control. It’s already included in .gitignore.
4

Create Database User and Database

Set up PostgreSQL for PhotoFlow:
# Access PostgreSQL as superuser
sudo -u postgres psql
In the PostgreSQL shell:
-- Create user
CREATE USER photoflow WITH PASSWORD 'photoflow_password';

-- Create database
CREATE DATABASE photoflow OWNER photoflow;

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE photoflow TO photoflow;

-- Exit
\q
On Windows, access PostgreSQL differently:
# Open SQL Shell (psql) from Start Menu
# Or use pgAdmin GUI tool
Then run the same SQL commands above.
5

Generate Prisma Client

Generate the Prisma client for type-safe database access:
npx prisma generate
This creates the @prisma/client package based on your schema.
6

Run Database Migrations

Create the database schema:
npx prisma migrate dev --name init
This command:
  • Creates the database if it doesn’t exist
  • Generates migration files in prisma/migrations/
  • Creates the Tasks and task_comments tables
  • Applies all migrations to your database
You should see a success message: “Your database is now in sync with your schema.”
7

Build the Application

Compile PhotoFlow for production:
npm run build
This:
  • Compiles SvelteKit components
  • Bundles JavaScript and CSS
  • Optimizes assets for production
  • Generates the build/ directory
Output indicates successful build:
✓ built in [time]ms
8

Start PhotoFlow

Launch the application:
npm run preview -- --host
The --host flag enables network access, allowing other PCs to connect. Omit this flag for localhost-only access.
You should see:

  ➜  Local:   http://localhost:4173/
  ➜  Network: http://192.168.1.100:4173/
9

Access the Application

Open your browser and navigate to:
http://localhost:4173
You should see the PhotoFlow dashboard with an empty Kanban board!

​
Development Mode

For development with hot module replacement: 
npm run dev
This starts the Vite dev server with:
  • Hot Module Replacement (HMR) - See changes instantly
  • Source maps - Better debugging
  • Fast refresh - No full page reloads
Dev server runs on http://localhost:5173 by default.
Use development mode when modifying PhotoFlow’s code. Use production mode (npm run preview) for actual usage.

​
Database Management

​
View Database with Prisma Studio

Prisma Studio provides a GUI for your database: 
npx prisma studio
Access at http://localhost:5555 to:
  • View all tasks and comments
  • Edit data directly
  • Test queries
  • Explore relationships

​
Reset Database

This deletes all data!
npx prisma migrate reset
This will:
  1. Drop the database
  2. Recreate it
  3. Apply all migrations
  4. Run seed scripts (if configured)

​
Create New Migrations

After modifying prisma/schema.prisma: 
npx prisma migrate dev --name descriptive_name
Example: 
npx prisma migrate dev --name add_priority_field

​
Project Structure

Understand PhotoFlow’s directory layout: 
PhotoFlow/
├── prisma/
│   ├── schema.prisma          # Database schema
│   └── migrations/            # Migration history
├── src/
│   ├── lib/
│   │   ├── components/        # Svelte components
│   │   ├── server/            # Server-side code
│   │   └── utils/             # Utility functions
│   └── routes/
│       ├── api/               # API endpoints
│       ├── dashboard/         # Kanban board UI
│       └── taskOverview/      # Task list view
├── static/                    # Static assets
├── .env                       # Environment variables (create this)
├── .env.example               # Environment template
├── package.json               # Dependencies
├── svelte.config.js           # SvelteKit config
├── vite.config.js             # Vite config
└── tailwind.config.js         # TailwindCSS config

​
Useful Commands

​
Package Management

# Install dependencies
npm install

# Update dependencies
npm update

# Check for outdated packages
npm outdated

​
Development

# Start dev server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Run with network access
npm run preview -- --host

# Use custom port
npm run preview -- --port 3000 --host

​
Code Quality

# Format code
npm run format

# Lint code
npm run lint

​
Database

# Generate Prisma client
npx prisma generate

# Run migrations
npx prisma migrate dev

# Deploy migrations (production)
npx prisma migrate deploy

# Open Prisma Studio
npx prisma studio

# Reset database
npx prisma migrate reset

​
Verification

Verify your installation is working:
1

Check Server is Running

Open http://localhost:4173 in your browser
2

Create a Test Task

  1. Click ”+ Neue Aufgabe hinzufügen” in any column
  2. Fill in task details
  3. Save and verify it appears on the board
3

Test Drag and Drop

Drag the task to a different column and verify it moves smoothly
4

Test Database Persistence

  1. Restart the server (Ctrl+C, then npm run preview -- --host)
  2. Refresh the browser
  3. Verify your task is still there

​
Next Steps

Network Setup

Configure multi-PC access for your team

Environment Variables

Learn about all configuration options

Kanban Board

Explore the Kanban workflow features

Docker Deployment

Deploy for production use

​
Troubleshooting

Run:
npx prisma generate
npm install
  1. Ensure PostgreSQL is running:
# Linux
sudo systemctl status postgresql

# macOS
brew services list
  1. Check your DATABASE_URL in .env
  2. Verify database credentials are correct
Use a different port:
npm run preview -- --port 3000 --host
Reset and recreate migrations:
npx prisma migrate reset
npx prisma migrate dev --name init
This deletes all data!
Clear cache and reinstall:
rm -rf node_modules package-lock.json
npm install
npm run build
If real-time sync isn’t working:
  1. Check browser console for errors
  2. Ensure VITE_SOCKET_URL is correct (optional, defaults to window.location)
  3. Verify no proxy or firewall is blocking WebSocket connections

Build docs developers (and LLMs) love

Get started for freeTalk to us