StreamSouk
[!IMPORTANT]
Status: Currently in active development for v2.0.0.
The platform is undergoing a complete rebuild. You can join the waitlist at StreamSouk to get notified once we're live.
Overview
StreamSouk is a video streaming platform built with a primary focus on learning and implementing those learnings.
The v2.0.0 Rebuild: Goals & Architecture
The current iteration of StreamSouk is a self-managed monorepo. The primary goals for this rebuild are:
- Advanced Media Handling: Learning engineering behind and implementing video, audio, and image processing from scratch.
- Frontend Excellence: Learning SEO and accessibility standards.
Run locally
Two ways, pick one:
- Run with Docker: one command, nothing to install but Docker.
- Run it manually: clone the repo and run the four processes yourself, with full control. This is the source of truth for how the app runs; the other sections and
CLAUDE.md "Commands" describe the same things.
Run with Docker
Docker is the only prerequisite (about 4 GB of RAM allocated to it).
git clone https://github.com/azeemuddinaziz/streaming.git
cd streaming
docker compose up
Open http://localhost:3001. The API is on :3000 and the upload server (tusd) on :8080.
- Stop:
docker compose down. Accounts, Videos and uploads survive the next up.
- Reset everything:
docker compose down -v (deletes the database, the uploaded bytes and the generated sign-in secret).
- Worker stuck or killed:
docker compose restart worker.
- After pulling changes:
docker compose up --build.
- Demo content: see Demo data.
Limits: the first build takes several minutes, and transcoding speed depends on your machine. Media and share links use localhost, so they only work on the same machine. This is not for production: no TLS, no backups, and bytes stay on disk instead of S3.
Demo data
The seed fills a fresh run with demo content, so the home page is not empty. It creates demo Users (demo-user-N), Videos (generated 8-second clips, processed by the worker like a real upload; one in six is Unlisted, the rest Public), Comments with Replies, Likes and Dislikes, and a ring of Subscriptions. It waits until every Video is ready (5 minute limit) and is safe to run again: it only adds what is missing.
| Flag | Range | Default |
|---|
--users N | 1 to 10 | 3 |
--videos N | 1 to 50 | 6 |
--comments-per-video N | 0 to 10 | 2 |
--help prints the same. The demo Users sign in with their email [email protected] (for example [email protected]) and the password demo-password, which is known to everyone, so use it on a local run only. The seed refuses to run under NODE_ENV=production or with S3_BUCKET set.
Run it manually
This is the source of truth for running StreamSouk from a clone. You run a Postgres database and four processes: the API, the background worker, the upload server (tusd) and the web app.
1. Prerequisites
| Tool | Version | macOS (Homebrew) | Linux (Debian/Ubuntu) |
|---|
| Node | 24 (what the Docker images use) | brew install node@24 | nvm install 24, or nodejs.org |
| pnpm | the repo pins 12.4.2 and pnpm downloads it when needed | brew install pnpm | npm i -g pnpm |
| Postgres | 17 (what Docker uses) | brew install postgresql@17 && brew services start postgresql@17 | sudo apt install postgresql && sudo systemctl start postgresql |
tusd | 2.x | brew install tusd | binary from the tusd releases, put on your PATH |
ffmpeg and ffprobe | any recent (one package provides both) | brew install ffmpeg | sudo apt install ffmpeg |
Check: node -v, pnpm -v, psql --version, tusd -version, ffmpeg -version, ffprobe -version.
2. Clone and install
git clone https://github.com/azeemuddinaziz/streaming.git
cd streaming
pnpm install
3. Create the databases
One for the app and a separate one the tests are allowed to wipe (only needed to run pnpm --filter server test).
createdb streamsouk
createdb streamsouk_test
On Linux the postgres user usually owns the server, so use sudo -u postgres createdb ... (and create a role for yourself with sudo -u postgres createuser --superuser $USER).
4. Configure
cp server/.env.example server/.env
cp web/.env.example web/.env.local
Edit server/.env:
DATABASE_URL=postgresql://<you>@localhost:5432/streamsouk (add :<password> after the user if your Postgres has one; on a default Homebrew or Postgres.app install there is none).TEST_DATABASE_URL=postgresql://<you>@localhost:5432/streamsouk_test (must differ from DATABASE_URL).JWT_SECRET: paste the output of openssl rand -base64 48.- Leave
WEB_ORIGIN as http://localhost:3001 and S3_BUCKET unset: uploaded bytes then stay on disk under server/data/.
web/.env.local works as copied.
5. Generate the client and migrate
pnpm --filter server generate
pnpm --filter server exec prisma migrate deploy
(pnpm --filter server migrate is prisma migrate dev, for changing the schema.) To prepare the test database too: DATABASE_URL=<your TEST_DATABASE_URL> pnpm --filter server exec prisma migrate deploy.
6. Start the four processes
One terminal each, from the repo root:
| Process | Command | Port |
|---|
| API | pnpm --filter server dev | 3000 |
| Worker (transcoding, cleanup) | pnpm --filter server worker | none |
| Upload server | pnpm --filter server tusd | 8080 |
| Web | pnpm --filter web dev | 3001 |
7. Check that it works
- Open http://localhost:3001 and choose Sign up: a name of 3 to 30 letters, digits or hyphens, an email and a password.
- Open Upload, choose a short video file and start the upload. The bar should reach 100%.
- Open Studio. The Video shows Processing with a progress bar, then Ready after the worker has made the HLS Renditions and the thumbnail (seconds for a short clip).
- In Studio choose Edit, give it a title and a description, set Visibility to Public and save. Watch plays it, and it appears on the home page.
Want demo content instead? See Demo data.
If the Video stays on Processing, look at the worker terminal. curl http://localhost:3000/api/v1/videos returning {"videos":[],...} confirms the API and the database.
Troubleshooting
- Port already in use (
EADDRINUSE on 3000, 3001 or 8080): stop the other process, or run the API on another port with PORT=<n> in server/.env (the tusd script reads it too, and also set API_URL and NEXT_PUBLIC_API_URL in web/.env.local). For the web app: pnpm --filter web exec next dev -p <n>, and set WEB_ORIGIN in server/.env and NEXT_PUBLIC_WEB_ORIGIN to match. If Docker is running, docker compose down frees all three.
tusd: command not found: install it (step 1) and make sure it is on your PATH; open a new terminal after installing.- Uploads fail with a network or CORS error:
pnpm --filter server tusd must be running, and WEB_ORIGIN in server/.env must be exactly the address in your browser (http://localhost:3001, not 127.0.0.1).
- Video fails or stays Processing:
ffmpeg and ffprobe must be on the worker's PATH; run ffmpeg -version. The worker must also be running. A failed Video has a Retry button in Studio.
- Signed in, but signed out again on reload: the cookie is not being set. Use
localhost for both the web app and the API (not an IP address or a mix), and keep NEXT_PUBLIC_API_URL pointing at the API's address.
JWT_SECRET or DATABASE_URL errors on start, or Environment variable not found: the file must be server/.env, and the commands must be run through pnpm --filter server.- Prisma client missing (
Cannot find module .../generated/prisma): run pnpm --filter server generate.
Historical Context (v1.0.0)
The legacy version of StreamSouk (v1) has been officially deprecated and taken offline to make way for the new infrastructure. It featured basic video upload via Cloudinary, user authentication, and profile management, utilizing separate frontend and backend repositories.
If you are interested in the legacy code or the architectural starting point of this project, you can view the historical snapshot here:
License
StreamSouk is released under the MIT License.
