Self-Hosting Guide

You can run your own Watermelon server for complete control over your music streaming backend. This guide covers local development and production deployment.

Prerequisites

• Node.js 18+ or later
• npm, pnpm, or yarn
• Supabase account (free tier works fine)
• (Optional) Telegram Bot Token for bot integration
• (Optional) Razorpay account for premium subscriptions
• yt-dlp binary — The server spawns yt-dlp as a child process

Local Setup

1. Clone the Repository

git clone https://github.com/watermelon-music/Watermelon-apk.git
cd watermelon-api

2. Install Dependencies

pnpm install

3. Set Up Supabase

1. Go to supabase.com and create a new project
2. Copy your Project URL and anon/public key
3. Create the required tables (users, playlists, favorites, etc.) using the SQL schema in the repo

4. Configure Environment Variables

Create a .env file in the project root:

PORT=3000
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key
RAZORPAY_KEY_ID=your_razorpay_key_id
RAZORPAY_KEY_SECRET=your_razorpay_key_secret
TELEGRAM_BOT_TOKEN=your_telegram_bot_token

Only SUPABASE_URL and SUPABASE_KEY are required for basic functionality. Razorpay and Telegram are optional.

5. Install yt-dlp

The server needs yt-dlp available in the system PATH:

# macOS/Linux
pip install yt-dlp
 
# Or download the binary directly
wget https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -O /usr/local/bin/yt-dlp
chmod +x /usr/local/bin/yt-dlp

6. Start the Server

pnpm start

The API server will start on http://localhost:3000.

Deploy to Render

Render is the recommended platform for hosting Watermelon.

1. Fork the repository on GitHub
2. Create a new Web Service on render.com
3. Connect your GitHub repository
4. Set the build command: pnpm install
5. Set the start command: pnpm start
6. Add all environment variables from the .env example
7. Click Create Web Service

The server will auto-deploy on every push to your main branch.

Update the Android App

After deploying your server, update the API URL in the Android app:

1. Open the project in Android Studio
2. Find the Constants.kt or network configuration file
3. Change the base URL to your deployed server
4. Rebuild and reinstall the APK

Troubleshooting

yt-dlp not found

Make sure yt-dlp is installed and available in the server environment. On Render, you might need to add a custom build script that installs yt-dlp.

Search returns empty results

Check that yt-dlp is working:

yt-dlp --dump-json "ytsearch3:test" | head -c 500

Supabase connection errors

Verify your SUPABASE_URL includes https:// and the SUPABASE_KEY is the anon key (not the service role key unless you know what you’re doing).

CORS errors

The Express server should already have CORS configured. If you see CORS errors, make sure the origin in the CORS config matches your Android app’s domain or use * for development.

Credits

Self-hosting Watermelon is possible thanks to generous free tiers from these platforms:

⭐ All of these offer generous free tiers for hobby projects. We recommend upgrading to paid plans as your usage grows.