Skip to main content

Troubleshooting

GitHub API rate limits during source fetch​

scripts/fetch-sources.sh uses the GitHub API to resolve releases, tags, and default branches. If unauthenticated requests hit a rate limit, set GITHUB_TOKEN or GH_TOKEN before building:

export GITHUB_TOKEN=<read-only-token>
make docker

Missing build/sources.manifest​

scripts/build.sh and scripts/package.sh require build/sources.manifest from the fetch step. Run:

scripts/fetch-sources.sh

or use the full orchestration:

make all

ModSecurity or OpenResty compile failures​

The ModSecurity build is memory hungry. In CI, MODSEC_MAKE_JOBS defaults to 1 and MAKE_JOBS is limited to reduce OOM risk. Locally, lower parallelism if the compiler is killed:

MAKE_JOBS=2 MODSEC_MAKE_JOBS=1 make all

Package installs but service does not start​

Check configuration first:

sudo openresty -t
sudo journalctl -u openresty --no-pager

The package maintainer scripts validate before starting or reloading. If validation fails, fix /etc/nginx or /etc/modsecurity and restart manually.

Port conflicts with Debian nginx​

The package conflicts with Debian nginx packages and the preinst script stops and disables nginx.service when present. If another service still owns port 80 or 443, inspect listeners:

sudo ss -ltnp 'sport = :80 or sport = :443'

Stop or reconfigure the conflicting service before starting OpenResty.

Default certificate warnings​

The postinst script generates a self-signed certificate when no certificate exists. Browser warnings are expected until you replace it with a real certificate and update the certificate include used by the HTTPS vhost.

Docusaurus build failures​

From website/, reinstall dependencies and clear the Docusaurus cache:

npm install
npm run clear
npm run build

If deployment produces broken links on GitHub Pages, verify DOCS_URL and BASE_URL. For project pages, BASE_URL should usually be /<repo-name>/. For an organization pages repository named <org>.github.io, use BASE_URL=/.