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) | bun (optional - zephyr-forge) | 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.

_{Using BUN (recommended)}

bunx zephyr-forge@latest setup

_{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 required containers and run migration containers required for prisma schema & minio buckets
pnpm run docker:dev
# Clean everything and start fresh if you encounter any issues
pnpm run docker:clean:dev && pnpm run docker:dev

# 3.5 (Optional) Run the migrations manually
pnpm run docker:dev-noinit # This will start the required services without running the migrations
cd packages/db && pnpm prisma generate && pnpm prisma db push
# For minio buckets, create the following buckets from the MinIO console at http://localhost:9001 
`uploads`, `temp`, `backups`

# 4. Start the development containers if not already started
pnpm run docker:start # (optional if you want to start the containers manually)

# 5. 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
# Some useful commands are:
pnpm run env:check # Check if all the required environment variables are set
pnpm run env:fix # Fix the missing environment variables (local development only)
pnpm run env:validate # Validate the environment variables

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

# TIP ⚠️ : Check package.json for more scripts in the root directory

_{// 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}

_{// 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 lint && pnpm run format

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}