openresty.org: The Source of the Site That Runs on OpenResty

A Project Site That Runs on Its Own Stack

The openresty.org repository holds the source code and configurations for the official OpenResty site, and the site is described as a dynamic web application built entirely upon the OpenResty stack, backed by the PostgreSQL database management system.

That choice is the interesting part. Most open source projects publish their site with a static site generator, and the dogfooding argument for doing the opposite is that the maintainers use their own product every day. Here the site is a live application with a database behind it, which is why there is a search page, why the blog list is generated, and why the release process involves regenerating data files.

The repository holds two generations of the site, with the latest one under the v2/ directory and the older one under v1/. The README documents the v2 workflow, and the top level is otherwise small, with the README, a .github/ directory and the two version directories.

The author is Yichun Zhang, also known as agentzh, who is the person behind OpenResty itself, and the copyright line runs 2011 to 2017 for OpenResty Inc. The module is licensed under the BSD licence, with the full three clause text in the README, and the related project mentioned in the See Also section is the OpenResty Survey web application.

The Build Needs pandoc, marked, cheerio and a Makefile

The build requirements are spelled out, and they explain the shape of the toolchain. You need both OpenResty and PostgreSQL 9.x, and then a set of command line and Node tools: pandoc, marked, cheerio, axios, pug and sharp, installed to your system.

On Mac OS X the README shows it as two commands:

brew install pandoc
npm install marked cheerio axios pug sharp

You also need perl installed for building the web site, though it is not needed for service deployment. The split matters, because it separates the one-off authoring tools from the runtime, and the runtime is OpenResty plus PostgreSQL and nothing else.

The actual build is a set of make targets, and the sequence in the README is the whole local development loop:

cd v2/

make gendata  # generate data files from .md files

make initdb   # create the database and load the data files
make run      # starting the test nginx server listened on localhost:8080
make reload   # for reloading the test nginx server

Between gendata and initdb there is a step the README spells out in full, because it is manual: you create the test database openresty_org and the test account openresty in your local PostgreSQL server, using the commands in the initial comment lines of the init.sql file.

The one performance note is about parallelism. If your machine has more than one spare CPU core, you can specify the -jN option of make to build the HTML docs in parallel, for example make gendata -j8, which runs the build in eight parallel jobs and so uses at most eight CPU cores.

PostgreSQL Reached Over Cosockets

The database layer is where the OpenResty stack is doing something specific rather than something generic.

The credits name leaf corcoran for contributing the pgmoon library, which is described as being for communicating with PostgreSQL via cosockets. Cosockets are the coroutine-based socket API that OpenResty exposes to Lua, and using them to talk to PostgreSQL means the database connection is part of the same event loop as the web request, so a query does not block a worker the way a separate connection pool would.

That is the whole point of a cosocket-based PostgreSQL driver, and it is why a site of this size can be served by an nginx built for streaming rather than for traditional request handling.

The site is not a read-only content repository either. The database holds the content that the application serves, and the build step loads the generated data files into it, so the pipeline is Markdown and templates in, database rows in the middle, HTML out.

The other credit in that section is Mashape, which contributed the page templates for the v2 version of the site, which tells you where the front end design came from.

A Custom I18n Layer Built on po Files Without gettext

The internationalisation setup is the least conventional part of the repository, and the README explains it in detail.

The.po files under po/ are for I18N, and the site needs to support both the English and Chinese versions. The files are similar to the.po files used by the classic GNU gettext toolchain, but the project does not use GNU gettext at all. The.po files are automatically updated according to the latest Lua source and the TT2 template files, and if you edit the.po files you have to re-run make for the changes to take effect, which updates the openresty_org.i18n Lua module file from the.po files.

So the format is gettext's, and the toolchain is not. The translation data ends up as a generated Lua module, which is what the application consumes at run time, and that avoids a dependency on the gettext binaries in the deployment environment.

The other half of the template story is the TT2 files. If you want to regenerate the openresty_org.templates Lua module from the TT2 template files under templates/, you need to install the Lemplate CPAN module:

sudo cpan Lemplate

and then just run make. Lemplate is a build-time dependency for regenerating that module.

There is a third generation path, for content that changes on its own. To update the list of blog posts you run make auto-templates, which also downloads images from the blog site, compresses those images and saves them into the header-images directory.

Releasing a New Version Means Editing a Fixed List by Hand

The release section is the most unusual documentation in the repository, because it describes a process that is entirely manual by design.

When you are ready to release a new version of OpenResty, you need to manually update a fixed list of files. The list spans both languages and several template kinds: the announcement file for Chinese and English, the changelog for Chinese and English, the download page for Chinese and English, the news templates for Chinese and English, and the Pug utility that renders them.

After that, you regenerate the site:

export PATH=$PWD/../../lemplate:$PATH
make clean
make

The PATH export is there because Lemplate lives in a sibling directory of the site tree, which is a small detail that will break a build if it is missed. The make clean step is what makes the regeneration clean rather than incremental, which matters when a template change has to propagate everywhere.

So the release process is: a human edits the announcement, the changelog and the download page for each language, a human adjusts the news templates, and the machine regenerates the whole site from those edits plus the content in the tree. Nothing is fetched from a content management system, and nothing is edited on the server.

The list of files is the contract. A release that forgets one of those files produces a site that is partly updated, and the README does not offer a script to catch that.

The TODO List Reads as a Design Document

The TODO section of the README is unusually detailed, and it is worth reading as a statement of where the authors think the site should go.

The first item is responsive design for the web page templates for mobile devices with small screens. The second is an in-memory caching layer for the openresty_org web app via lua-resty-lrucache and/or lua_shared_dict, which is the kind of change that belongs to the application layer rather than to the static content. The third is translating more English .md documents into Chinese, which is a content pipeline question.

Then there are feature items: a pager to the search result page, an RSS feed endpoint in the app, and another tab page on the right-hand side bar featuring the top N hot pages, which is the kind of thing that needs a view in the database and a query to back it.

The last two are infrastructure. Adding an OpenResty logo to the web page header is cosmetic, and removing the dependency on pandoc by migrating to a standalone Perl script is the interesting one, because it would take a build-time dependency out of the toolchain for everyone who only wants to rebuild the site.

The ordering is informative. A responsive layout and a search pager are user-facing and cheap, the caching layer is a performance decision, and the pandoc removal is a cleanup that only matters once the toolchain has settled.

Editorial conclusion

This repository fits a reader who wants to see how a project builds its public site with the same stack it ships, since the site runs on OpenResty with Lua, cosockets and PostgreSQL rather than a separate static site generator, and it fits a contributor who wants to propose a documentation change. It is a poor fit as a template for a new site, because the build assumes a developer who already has OpenResty, PostgreSQL 9, pandoc, a Perl Lemplate install and the CPAN toolchain, and because the i18n pipeline is custom rather than gettext. Before changing anything, read the release section, since publishing a new OpenResty version means editing a fixed list of template and changelog files by hand before regenerating the site. The module is BSD licensed, the site source lives under v2/, and the last push was on 2026-09-23.

Frequently asked questions

Official sources

1. Issues
2. openresty/openresty.org on GitHub
3. Project website
4. README