Waline: a self-hosted comment backend that runs on serverless free tiers

The gap Waline fills between Disqus and a hand-written comment table

Static site generators produce HTML with no server process, so a comment form has nowhere to write. The two common answers are a hosted third-party widget or a backend you build yourself. Waline takes a third position: it ships a browser client, @waline/client, and a separate server package, @waline/vercel, that you deploy to a serverless platform. The README describes it as "A simple comment system with backend support" and lists Disqus among its repository topics, which places it squarely in the replace-your-hosted-widget category. The intended user is someone running a blog, documentation site or personal publication generated as static files, who wants the comment thread stored in a database they can query and export, and who is willing to perform one deployment step to get there. The README also lists MiniValine and sodesu as alternative clients against the same backend, so the client is not the only entry point. If your site already runs an application server with a database, Waline adds a second deployment surface for something you could implement directly, and that is worth weighing before adopting it.

Two deployable pieces, one database, and where the data actually lives

The architecture visible in the README is a three-column table: client, server, storage. The client is @waline/client, loaded in the browser. The server is a deployment of @waline/vercel, which the README lists as deployable to Vercel, CloudBase, Railway, Render, Zeabur, Netlify, Alibaba Cloud ComputeNest, Docker, or a self-hosted machine. Storage is a separate choice: PostgreSQL, MySQL, SQLite, TiDB, MongoDB, CloudBase, or GitHub. The README claims "at least 243 deployment choice", which is the product of the server and storage columns rather than a measured figure, so treat it as a marketing count and not a compatibility guarantee. The practical consequence is that the server process is stateless with respect to comments: it reads and writes through a storage adapter, so the database is the durable component and the function can be redeployed or moved without migrating comment text by hand. That is the design decision that makes the serverless targets viable at all. It also means the storage choice is the decision with the longest consequences, because switching from, say, SQLite to PostgreSQL later is a data migration you own, and the README does not describe a migration tool.

What the feature list covers, and what it leaves open

The README's Todo list is unusually informative because most entries are checked. Email, WeChat, QQ and Telegram notifications are marked done, as are Akismet integration, article counters, i18n with custom language support, login, comment management and deletion, IP-based rate limiting, keyword restrictions, an IP disallow list, duplicate content detection, social account login, sticky comments and comment likes. The single unchecked item is "AWS, GCP, Azure deploy support", which tells you the deployment story is complete for the platforms listed in the table and absent for the three largest cloud providers outside Alibaba Cloud. If your infrastructure is already on AWS, GCP or Azure, you are deploying the Docker image or a self-hosted Node process rather than using a first-party integration. The spam controls are the part worth reading closely: rate limiting, keyword restrictions, a disallow list and duplicate detection are all rule-based, and Akismet is the only external classifier named. There is no mention of a machine-learning spam filter, so a site that attracts determined manual spam will need the disallow list maintained by hand.

Getting it running: the client script and the server deployment

The README does not reproduce installation commands, so the concrete steps have to come from the documentation site at waline.js.org rather than this repository file. What the README does establish is the shape of the setup: you deploy the server package, pointed at one of the listed storage services, and then load @waline/client in your page against that server's URL. The npm packages are named @waline/client and @waline/vercel, and the README exposes version and bundle-size badges for both, which is how you confirm the current published version before pinning one. Deployment targets are given as a list of platforms rather than as configuration snippets, and Docker and self-host are listed as first-class options alongside the managed platforms. The honest summary is that this repository's README is a signpost, not a setup guide: it links to the English and Simplified Chinese documentation and stops there. Anyone evaluating Waline should read the deployment page for their specific platform before deciding, because the environment variables and storage credentials differ per target and none of them appear in the material available here.

The serverless dependency is the real constraint

Waline's free-deployment pitch rests on serverless platforms, and that is also its sharpest limitation. A serverless function on a free tier has cold starts, execution time limits and request quotas that the README does not quantify. A comment thread on a low-traffic blog will sit idle for long stretches, so the first visitor after a quiet period pays the cold-start cost on a request that also has to open a database connection. That combination is the classic failure mode for this architecture, and nothing in the supplied material indicates how Waline mitigates it or whether connection pooling is part of the server package. The second constraint is that your comment system now depends on a third-party platform's continued willingness to host it on a free plan. Terms change. If the function is suspended, comments stop working immediately and silently from the reader's perspective. Self-hosting the server on Docker removes that dependency at the cost of running a process, which is precisely the thing a static site was avoiding. Neither path is wrong, but the README presents the deployment matrix as pure choice without naming this trade-off.

Waline against Isso, and what the difference in approach means

Isso is the closest well-known alternative in the same category: a self-hosted comment server for static sites, written in Python, that you run as a persistent process behind a reverse proxy and that stores comments in SQLite or MySQL. The difference in approach is structural rather than cosmetic. Isso is one long-running server you operate; Waline is a function you deploy to someone else's platform plus a storage service you choose separately. Isso gives you predictable latency because the process is always up, and it gives you one thing to back up. Waline gives you no server to patch and a deployment that scales to zero, at the cost of cold starts and a dependency on the hosting platform. Isso's setup assumes you are comfortable running a daemon and a proxy; Waline's assumes you can follow a platform's deploy flow and paste database credentials into environment variables. If you already run a VPS for other reasons, Isso's model is simpler to reason about. If you have no server at all and no intention of getting one, Waline's model is the only one of the two that fits.

Licence, maintenance surface and what upgrading costs you

Waline is licensed GPL-2.0. That is a copyleft licence, and it applies to the server package you deploy. Running the server for your own blog is not distribution, so the common case of a personal site carries no obligation beyond keeping the licence text intact. Distributing a modified version, or shipping Waline inside a product you hand to customers, triggers obligations that differ from permissive licences, and that is a question for your own counsel rather than something to settle from a README. On maintenance: the repository shows a last push in September 2026 and no releases were retrieved for this profile, so the release cadence cannot be judged from the material here. Two things to verify yourself before adopting. First, check the npm registry for the current published versions of @waline/client and @waline/vercel rather than trusting the badges. Second, check the documentation for your chosen storage adapter, because the storage column lists seven options and the effort of switching between them is not described anywhere in this README. The upgrade path for the client is a script tag or a package bump; the upgrade path for the server is a redeploy; the upgrade path for the database is yours to plan.

Editorial conclusion

Adopt Waline if you run a static site generator, are willing to deploy and maintain a separate backend function, and want comments stored in a database you control. Do not adopt it if you want a hosted service with no deployment step, or if GPL-2.0 obligations conflict with how you ship your site. Before committing, verify which storage adapter and deployment target you will actually use, confirm that your chosen free tier still permits the function, and check whether the notification channel you need is listed as complete or still on the Todo list.

Official sources

1. Issues
2. License: GPL-2.0
3. Project website
4. README
5. walinejs/waline on GitHub