Development 
     
 Contributing 
     
 Wiki 
     
 Roadmap 
     
 Screenshots 
     
 Troubleshoot 
   

_{// Project Overview}

Zephyr is a Social aggregator, part social media platform, part news aggregator. It is a platform that allows users to share and discover content from around the web. Completly open-source and community-driven, Zephyr is a platform that is built by the community, for the community.

_{// Sub-services under Zephyr}

Zephyr Services (GITEA) | Zephyr Support | Velastria / Zephyr chat | Zephyr Forge

_{// Local Development Setup}

Note

Note for SWOC contributors: Zephyr is a large project with multiple services and dependencies. The Issues page containes list of issues that may or may not be suitable for SWOC contributions. Check ISSUES with SWOC label for issues that are suitable for SWOC contributions. If you are unsure about the issue, feel free to ask in the issue thread. You can also create a new issue with SWOC label for any feature or bug you want to work on.

_{// Prerequisites}

Node.js (v20 or higher) | pnpm (Workspace management) | Docker (Containerization) | Git (Version control)

_{// Installation}

Note

Zephyr is a monorepo project, which means that it is composed of multiple packages that are managed together. The project uses pnpm for workspace management and Docker for containerization. Make sure you have the following prerequisites installed before setting up the development environment.

_{Using Zephyr Forge (recommended)}

Zephyr Forge is a powerful utility designed to streamline the setup process for Zephyr development environments. It automates the entire configuration process, handling everything from dependency checks to Docker container management.

_{Linux & MacOS}

curl -fsSL https://forge.zephyyrr.in/install.sh | bash

_Windows

irm https://forge.zephyyrr.in/install.ps1 | iex

_{Manual Installation}

# 1. Clone the repository
git clone https://github.com/zephyr.git && cd zephyr

# 2. Install the dependencies
pnpm install

# 3. First time setup or after clean
# This will start the development server using docker and create the required services & prisma migrations
pnpm run start

# Clean everything and start fresh
pnpm run docker:clean:dev && pnpm run start

# 4. Set `.env` variables form `.env.example` file (optional if you want auth and other services)
cp .env.example .env # Unix/Linux/Mac
copy .env.example .env # Windows
# Read the `.env.example` file for more information

# 5. Start the development server
pnpm turbo dev
# or
turbo dev

# Check package.json for more scripts in the root directory

Tip

start script uses docker-compose to start the required services & migrations. Check individual script in docker/scripts folder for more information.

_{// Ports:}

If everything goes well, you should be able to access the following services:

• Next.js: http://localhost:3000
• PostgreSQL: http://localhost:5433
• Redis: http://localhost:6379
• MinIO Console: http://localhost:9001 or http://localhost:9000

_{// Project Structure}

This is a high-level overview of the monorepo structure, check the individual package for more sub-packages and details.

/zephyr          - Root directory
  /apps
   /web          - web app (main)
  /packages
   /aggregator   - Aggregator service
   /auth         - Authentication & Email
   /config       - Shared configs & utils
   /db           - Database & Cache
   /ui           - UI components
  /docker         - Container configs & scripts

_{// Screenshots}

Homepage	Notifications	Bookmarks

Profile	Chat	Users

_{// Troubleshooting}

Tip

Try pnpm run docker:interactive: Docker utility to clean and manage the docker services for Zephyr.

_{// pre commit hooks}

If you encounter any issues with the pre-commit hooks, try running the following commands:

# Ensure that your code is formatted and linted
pnpm run biome:fix

If you encounter any issues with the development setup, try the following steps:

_{// Database}

If you encounter any issues with Prisma or the migrations failed, try running the following commands:

# Navigate to the db package
cd packages/db

# Run the following commands
pnpm prisma generate
pnpm prisma db push

_{// Minio (Object Storage)}

If you encounter any issues with Minio or the buckets are not created, try the following steps:

# Ensure MinIO is running
Access MinIO Console at http://localhost:9001

# Login with default credentials:
Username: minioadmin
Password: minioadmin

Create the following buckets:

- uploads
- temp
- backups

If you still encounter any issues with the development server, report the issue on the Issues page.

_{// Analytics}

_{// Contributors}

_{// Hall of Fame}

Zephyr is licensed under the AGPL License.

_{// Copyright © 2025 Parazeeknova}