Serial

A calm, customizable, and non-algorithmic RSS reader. Lots of customization options and great support for video content. Fully open source and easily self-hostable.

Check it out →

Releases & Changelog

All release notes can be found at https://serial.tube/releases.

Local Development

Getting up and running with Serial is easy. Here are the steps you need to start developing locally:

1. Clone the repository locally
2. Install the Turso CLI: https://github.com/tursodatabase/turso-cli
3. Copy apps/app/.env.example to apps/app/.env
4. Set PUBLIC_BASE_URL to http://localhost:3000
5. Navigate to Better Auth and generate an auth secret. Set it as BETTER_AUTH_SECRET
6. Install Node.js 22.12 or newer.
7. Install pnpm if you don't have it already.
8. Run pnpm i to install packages.
9. Run pnpm dev to create, migrate, and run your database for the first time, then boot up the development server.

If you'd like to support additional features in development, see below!

Self Hosting

Self hosting Serial is relatively easy. Here are the current platform-specific guides:

• Coolify (supports local and cloud db)
• Vercel (supports only cloud db)

If your preferred platform doesn't have a guide, follow these rough steps:

1. Fork the megaflorasoftware/serial repository to your own GitHub account.
2. Use a git-based deployment system to deploy when a new commit happens. There are a few ways to do this:
   • If deploying through Docker, the provided Dockerfile and Compose files build the app from the monorepo root
   • If building from source, build with pnpm --filter @serial/app build:artifact and start with pnpm start.
3. Set up a custom domain (if desired)
4. Set up your database:
   • If you want to use a local libsql database, use the provided docker-compose.yaml configuration. The database requires no additional configuration, but the application variables below are still required.
     • It's less common, but you can also manually provide your local libsql server URL in DATABASE_URL.
   • If you want to use a cloud libsql database provider (like Turso), set up a database with them and add your DATABASE_AUTH_TOKEN and DATABASE_URL to your environment variables.
5. Set PUBLIC_BASE_URL to the public origin URL where Serial will be available, such as https://serial.example.com.
6. Navigate to Better Auth and generate an auth secret. Set this as BETTER_AUTH_SECRET in your environment variables.
7. Deploy your application. Docker images read public configuration when the container starts, so the same image can be used at different domains without rebuilding it.
8. To update Serial in the future, sync your forked code from the main repo and the app will redeploy.

If you'd like to support additional features, see below!

Enabling additional features

Serial takes a model of progressive enhancement for features. The app can run with very few external dependencies, but services can be enabled whenever you want for whatever you need for your specific instance.

Email support (for password reset, etc)

Serial supports Resend and SendGrid as email providers. Only one is used at a time — if both keys are set, Resend takes priority.

• Resend: Create an account, add your RESEND_API_KEY to .env or your host's environment variables UI.
• SendGrid: Create an account, set up a mailing address, add your SENDGRID_API_KEY to .env or your host's environment variables UI.

Instapaper integration

• Register a new Instapaper OAuth application using their form.
• Wait to receive your OAuth credentials
• Add your INSTAPAPER_OAUTH_ID and INSTAPAPER_OAUTH_SECRET to .env or your host's environment variables UI.

AT Protocol integration

Serial supports allowing users to sign in with their AT Protocol handle. To enable this on your instance, do the following:

Run the following command in a terminal, and use the output as the value of the ATPROTO_STORE_ENCRYPTION_KEY environment variable:

openssl rand -base64 32

Run the following command in a terminal, and use the output as the value of the ATPROTO_CLIENT_PRIVATE_KEYS environment variable:

node -e "crypto.subtle.generateKey({name:'ECDSA',namedCurve:'P-256'},true,['sign']).then(async k=>console.log(JSON.stringify({kid:crypto.randomUUID(),...await crypto.subtle.exportKey('jwk',k.privateKey)})))"

Keep in mind that you may need to put those variables in quotes or mark them as "literal", as they will have special characters as part of their output.

That's it! You should be up and running with the AT Protocol. Keep in mind that you can set the displayed authentication methods in your Admin settings, which may be useful if you'd like to configure the allowed sign-in methods.

The following are very optional, but advanced users should know that they can also set:

• ATPROTO_PLC_DIRECTORY_URL: This defaults to https://plc.directory, but you can use an alternate source if you'd like to depend less on Bluesky's infrastructure.
• ATPROTO_APPVIEW_URL: This defaults to https://public.api.bsky.app for use in generating handle autocomplete suggestions, but you can use an alternate source if you'd like to depend less on Bluesky's infrastructure.