Skip to content
Klutch.sh Docs

Deploying uWave

Introduction

uWave (pronounced you-wave) is a collaborative listening platform that brings people together through shared music experiences. Users take turns playing songs from YouTube and SoundCloud in a virtual room where everyone listens together in real-time. Think of it as a modern take on playlist.com or turntable.fm with a focus on community and simplicity.

Built with Node.js and React, uWave provides a polished web interface where users can build playlists, join the DJ queue, vote on tracks, and chat with other listeners. The platform supports multiple media sources and features a robust plugin system for customization.

Key highlights of uWave:

  • Collaborative Listening: Everyone hears the same song at the same time
  • DJ Queue: Take turns playing music for the room
  • Multi-Source: Play music from YouTube and SoundCloud
  • Voting System: Upvote or downvote the current track
  • Chat Integration: Real-time chat alongside the music
  • User Playlists: Build and manage personal playlists
  • Customizable Rooms: Configure room settings and appearance
  • User Roles: Managers, moderators, and regular users
  • History Tracking: See what songs have been played
  • Plugin System: Extend functionality with plugins
  • Open Source: Licensed under MIT

This guide walks through deploying uWave on Klutch.sh using Docker, configuring your community room, and managing the listening experience.

Why Deploy uWave on Klutch.sh

Deploying uWave on Klutch.sh provides several advantages for running your collaborative listening room:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds uWave without complex configuration. Push to GitHub, and your music room deploys automatically.

Persistent Storage: Attach persistent volumes for user data, playlists, and history. Your community’s data survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, essential for secure authentication and real-time WebSocket connections.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on expected concurrent listeners.

Environment Variable Management: Securely store API keys and secrets through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain for your music community.

Always-On Availability: Your listening room remains accessible 24/7 for members around the world.

Prerequisites

Before deploying uWave on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • A Google Cloud account for YouTube Data API access
  • A MongoDB instance (can be deployed on Klutch.sh or use a managed service)
  • A Redis instance for real-time features
  • Basic familiarity with Docker and Node.js

Understanding uWave Architecture

uWave consists of several interconnected components:

u-wave-core: The Node.js backend server handling authentication, user management, playlist storage, and the DJ booth logic.

u-wave-web: The React frontend providing the user interface for interacting with the room.

MongoDB: Stores user accounts, playlists, media metadata, and room history.

Redis: Handles real-time features including the DJ waitlist, voting, and live updates.

WebSocket Server: Enables real-time communication between the server and connected clients.

Media Sources

uWave supports multiple media sources through plugins:

SourceDescription
YouTubeVideos and music from YouTube
SoundCloudTracks from SoundCloud

Preparing Your Repository

To deploy uWave on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

uwave-deploy/
├── Dockerfile
├── server.js
├── config.json
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for uWave:

FROM node:20-alpine


# Install build dependencies
RUN apk add --no-cache python3 make g++ git


# Create app directory
WORKDIR /app


# Initialize package.json
RUN npm init -y


# Install uWave packages
RUN npm install u-wave-core u-wave-http-api u-wave-web \
    u-wave-source-youtube u-wave-source-soundcloud


# Copy server configuration
COPY server.js /app/server.js
COPY config.json /app/config.json


# Create non-root user
RUN adduser -D -u 1000 uwave
RUN chown -R uwave:uwave /app
USER uwave


# Environment variables
ENV NODE_ENV=production
ENV PORT=6042


# Expose web port
EXPOSE 6042


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:6042/health || exit 1


# Start uWave
CMD ["node", "server.js"]

Server Configuration

Create a server.js file:

const uwave = require('u-wave-core');
const createWebApi = require('u-wave-http-api');
const createWebClient = require('u-wave-web/middleware').default;
const youTubeSource = require('u-wave-source-youtube');
const soundCloudSource = require('u-wave-source-soundcloud');


const port = process.env.PORT || 6042;


async function start() {
  const uw = uwave({
    mongo: process.env.MONGODB_URI,
    redis: process.env.REDIS_URL,
    secret: process.env.SECRET_KEY,
  });


  // Configure YouTube source
  if (process.env.YOUTUBE_API_KEY) {
    uw.source(youTubeSource, {
      key: process.env.YOUTUBE_API_KEY,
    });
  }


  // Configure SoundCloud source
  if (process.env.SOUNDCLOUD_API_KEY) {
    uw.source(soundCloudSource, {
      key: process.env.SOUNDCLOUD_API_KEY,
    });
  }


  // Create HTTP API
  const httpApi = createWebApi(uw, {
    secret: process.env.SECRET_KEY,
  });


  // Create web client
  const webClient = createWebClient(uw, {
    title: process.env.ROOM_NAME || 'uWave Room',
  });


  // Start the server
  const server = httpApi.listen(port, '0.0.0.0');


  // Mount web client
  httpApi.use(webClient);


  console.log(`uWave server running on port ${port}`);


  // Graceful shutdown
  process.on('SIGTERM', async () => {
    console.log('Shutting down...');
    await uw.close();
    server.close();
    process.exit(0);
  });
}


start().catch(err => {
  console.error(err);
  process.exit(1);
});

Configuration File

Create a config.json file for additional settings:

{
  "room": {
    "name": "My uWave Room",
    "description": "A collaborative listening experience",
    "welcomeMessage": "Welcome to the room! Add songs to your playlist and join the DJ queue."
  },
  "booth": {
    "maxPlayDuration": 480000,
    "skipVoteThreshold": 0.5
  },
  "users": {
    "allowGuests": false,
    "requireEmail": true
  }
}

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
node_modules

Environment Variables Reference

VariableRequiredDefaultDescription
MONGODB_URIYes-MongoDB connection string
REDIS_URLYes-Redis connection URL
SECRET_KEYYes-Secret key for sessions and tokens
YOUTUBE_API_KEYRecommended-Google/YouTube Data API key
SOUNDCLOUD_API_KEYNo-SoundCloud API key
ROOM_NAMENouWave RoomDisplay name for your room
PORTNo6042HTTP server port

Deploying uWave on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

    Set Up Required Services

    uWave requires MongoDB and Redis. You can:

    • Deploy them on Klutch.sh
    • Use managed services like MongoDB Atlas and Redis Cloud

    Note your connection strings for environment variables.

    Get API Keys

    Obtain necessary API keys:

    1. YouTube Data API: Create a project in Google Cloud Console, enable the YouTube Data API v3, and create an API key
    2. SoundCloud API: Apply for API access through SoundCloud’s developer portal (optional)

    Generate Secret Key

    Create a secure random string for session management. Use at least 32 characters.

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub:

    Terminal window
    git init
    git add .
    git commit -m "Initial uWave deployment configuration"
    git remote add origin https://github.com/yourusername/uwave-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project. Name it something descriptive like “uwave” or “music-room”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select your uWave repository.

    Configure HTTP Traffic

    uWave serves its interface over HTTP:

    • Select HTTP as the traffic type
    • Set the internal port to 6042

    Set Environment Variables

    Configure the following environment variables:

    VariableValue
    MONGODB_URIYour MongoDB connection string
    REDIS_URLYour Redis connection URL
    SECRET_KEYYour generated secret key
    YOUTUBE_API_KEYYour YouTube Data API key
    ROOM_NAMEYour room’s display name

    Attach Persistent Volumes

    Add persistent storage:

    Mount PathRecommended SizePurpose
    /app/data5 GBApplication data and cache

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will:

    • Build the container image
    • Install uWave and dependencies
    • Start the server
    • Provision an HTTPS certificate

    Access Your Room

    Once deployed, access your uWave room at your deployment URL. Register the first account to become the room admin.

Initial Setup and Configuration

Creating the Admin Account

The first user to register becomes the administrator:

  1. Navigate to your uWave room
  2. Click “Register” or “Sign Up”
  3. Create your account with email and password
  4. You automatically receive admin privileges

Room Configuration

Configure your room through the admin panel:

SettingDescription
Room NameDisplay name shown to users
DescriptionRoom description on the landing page
Welcome MessageMessage shown when users join
Max Song DurationMaximum length for played tracks
Skip ThresholdPercentage of votes needed to skip

User Roles

uWave supports multiple user roles:

RoleCapabilities
AdminFull control over room settings and users
ManagerCan promote/demote moderators, manage history
ModeratorCan skip songs, remove users from queue
DJCan add songs to playlists and join queue
UserCan listen, chat, and vote

Using uWave

Building Playlists

  1. Search for songs using the search bar
  2. Click the add button to add to your playlist
  3. Organize songs within your playlist
  4. Create multiple playlists for different moods

Joining the DJ Queue

  1. Select a playlist to play from
  2. Click “Join Queue” to enter the waitlist
  3. When your turn comes, your selected song plays
  4. After your song finishes, you move to the back of the queue

Voting and Interaction

  • Upvote: Show appreciation for the current song
  • Downvote: Indicate you don’t like the current song
  • Grab: Add the current song to your playlist
  • Chat: Discuss music and interact with others

Production Best Practices

Security Recommendations

  • Strong Secret Key: Use a long, random secret key
  • HTTPS Only: Always use HTTPS for production
  • API Key Protection: Never expose API keys in client code
  • User Moderation: Appoint trusted moderators
  • Registration Control: Consider invite-only registration

Performance Optimization

  • MongoDB Indexes: Ensure proper indexes for queries
  • Redis Persistence: Configure Redis persistence appropriately
  • Connection Pooling: Use connection pooling for databases
  • Resource Allocation: Scale based on concurrent users

Community Management

  • Clear Rules: Establish and communicate room rules
  • Active Moderation: Maintain an active moderation team
  • Regular Cleanup: Clean up inactive users and old data
  • Backup History: Regularly back up play history

Troubleshooting Common Issues

Connection Issues

Symptoms: Users cannot connect or experience disconnections.

Solutions:

  • Verify WebSocket connectivity through HTTPS
  • Check Redis connection for pub/sub
  • Review server logs for errors
  • Ensure adequate resources for concurrent connections

Media Playback Issues

Symptoms: Songs don’t play or show errors.

Solutions:

  • Verify YouTube API key is valid and has quota
  • Check if specific videos are restricted
  • Ensure proper permissions for API access
  • Review source plugin configuration

Authentication Problems

Symptoms: Users cannot log in or sessions expire.

Solutions:

  • Verify secret key is consistent across restarts
  • Check Redis connection for session storage
  • Clear browser cookies and try again
  • Review MongoDB connection for user data

Additional Resources

Conclusion

Deploying uWave on Klutch.sh gives you a collaborative listening platform where your community can share and discover music together. The combination of uWave’s engaging social features and Klutch.sh’s deployment simplicity means you can create a vibrant music community without managing complex infrastructure.

Whether you’re building a public listening room or a private space for friends, uWave on Klutch.sh provides the foundation for shared musical experiences that bring people together.