Quick Start Guide

Quick Start Guide

Get up and running with the Surkyl Platform monorepo in just a few minutes.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js: v18 or higher (Download)
• pnpm: v8 or higher (npm install -g pnpm)
• Rust: Latest stable version (Install)
• PostgreSQL: v14 or higher (for backend development)
• Docker: Latest version (optional, for containerized services)

Installation

1. Clone the Repository

git clone <repository-url>
cd aio

2. Install Dependencies

pnpm install

This will install all dependencies for the entire monorepo.

Running Applications

Development Server

To run any application in development mode:

# Run the playground app (Angular)
nx serve playground

# Run the docs site (Astro Starlight)
nx serve docs

# Run MueSync landing page
nx serve muesync-com

# Run Surkyl website
nx serve surkyl-com

Rust Applications

For Rust applications, use the standard Nx commands:

# Build Rust applications
nx build gate
nx build surkyl-server
nx build godseye-proxy

# Run Rust applications in development
cargo run --bin gate
cargo run --bin surkyl-server
cargo run --bin godseye-proxy

Building for Production

Build All Projects

nx build <project-name>

Examples:

# Build Angular app
nx build playground

# Build Astro site
nx build docs
nx build muesync-com
nx build surkyl-com

# Build Rust applications
nx build gate
nx build surkyl-server

Running Tests

Unit Tests

# Run tests for a specific project
nx test <project-name>

# Run tests for Angular library
nx test pixel

# Run Rust tests
nx test gate
cargo test

E2E Tests

# Run E2E tests with Playwright
nx e2e playground-e2e
nx e2e identity-ui-e2e

Common Tasks

View Project Graph

Visualize the dependency graph of your monorepo:

nx graph

Show Available Tasks

See all available tasks for a project:

nx show project <project-name>

Lint Code

# Lint a specific project
nx lint <project-name>

# Lint all projects
nx run-many --target=lint --all

Format Code

# Format all files
nx format:write

# Check formatting
nx format:check

Database Setup (for Surkyl Server)

If you’re working with surkyl-server, you’ll need to set up PostgreSQL:

1. Install PostgreSQL

# macOS
brew install postgresql@14

# Ubuntu/Debian
sudo apt-get install postgresql-14

# Start PostgreSQL
brew services start postgresql@14  # macOS
sudo systemctl start postgresql     # Linux

2. Create Database

createdb surkyl_server

3. Run Migrations

cd apps/surkyl-server
sqlx database setup

4. Configure Environment

Create apps/surkyl-server/configs/surkyl-server.config.yml or set environment variables:

database:
  url: postgresql://postgres:postgres@localhost:5432/surkyl_server

security:
  jwt_secret: your-secret-key-change-this-in-production

Docker Development

Some services provide Docker Compose configurations:

# Run Gate with Docker
cd apps/gate
docker-compose up

# Run Surkyl Server with Docker
cd apps/surkyl-server
docker-compose up

# Run GodSEye Proxy
cd apps/godseye-proxy
docker-compose up

IDE Setup

VS Code

Install the recommended extensions:

1. Open the workspace in VS Code
2. When prompted, install recommended extensions
3. Or manually install from .vscode/extensions.json

IntelliJ / WebStorm

The Nx plugin is available for JetBrains IDEs.

Nx Console

For a better developer experience, install Nx Console:

• VS Code: Nx Console Extension
• IntelliJ: Available in the plugin marketplace

Troubleshooting

Port Already in Use

If you get a port conflict error, check for running processes:

# Find process using port 4200
lsof -i :4200

# Kill the process
kill -9 <PID>

Rust Build Errors

If Rust builds fail:

# Update Rust
rustup update

# Clean build artifacts
cargo clean

# Rebuild
cargo build

Node Module Issues

If you encounter module resolution issues:

# Clean install
rm -rf node_modules
pnpm install

# Clear Nx cache
nx reset

Next Steps

Now that you’re set up, explore:

• Monorepo Structure - Understand the codebase organization
• Apps Overview - Learn about each application
• Contributing Guide - Start contributing to the project
• API Reference - Explore the APIs

Getting Help

If you run into issues:

1. Check this documentation
2. Review the project-specific README files
3. Check existing GitHub issues
4. Open a new issue if needed