pixies

Thanks for helping improve Pixies, a self-hosted speed-test analytics application.

Prerequisites

• Bun 1.4 or newer (runtime, package manager and build tool)
• Git
• Docker, only if you want to test the container image

Development setup

git clone https://github.com/ikhsanddy/pixies.git
cd pixies
bun install
cd client && bun install && cd ..
bun run dev

bun run dev generates the migration and integration indexes, starts the API on port 5216 and the dashboard dev server on Vite's default port. Generated indexes (server/migrations/index.js, server/integrations/index.js) are build artifacts; edit the individual migration or integration files instead.

For the additional apps:

cd web && bun install && bun run dev    # landing page
cd docs && bun install && bun run dev   # documentation site

Project layout

client/   React 19 dashboard (Vite, PWA)
server/   Bun + Express 5 API, Sequelize models, migrations, integrations
web/      Landing page (React + Vite)
docs/     VitePress documentation
scripts/  Installer, uninstaller and code generators

Code style

• Plain JavaScript and JSX. Do not add TypeScript files or types.
• Follow the existing indentation, naming and import conventions of the directory you edit.
• Styles are written in SCSS/Sass next to the components that use them.
• Keep changes focused; do not reformat unrelated code or commit build output.
• All locale files in client/public/assets/locales/ are edited here. Submit translation updates as pull requests.

Commit messages

Use Conventional Commits:

feat: add Gotify notification template
fix: handle missing certificates on startup
docs: clarify reverse proxy setup
chore: bump client dependencies

Allowed types include feat, fix, docs, style, refactor, perf, test, build, ci, chore and revert. Keep the subject in the imperative mood and under 72 characters. Reference issues in the footer, for example Fixes #123.

Pull requests

1. Open an issue first for larger changes so the approach can be discussed.
2. Fork the repository and create a branch from master.
3. Make the change and verify it locally:
   • bun run generate-migrations && bun run generate-integrations
   • cd client && bun run build
   • cd web && bun run build
   • cd docs && bun run build
4. Fill in the pull request template, including what changed and how you tested it.
5. Keep one logical change per pull request. Do not include generated indexes or build output; translation updates are welcome as their own pull requests.

CI runs the same build steps on pushes and pull requests to master. A pull request is merged once CI passes and a maintainer has reviewed it.

Reporting bugs

Open an issue using the bug report template and include:

• Pixies version and installation method (binary, Docker, source)
• Operating system and browser
• Steps to reproduce, expected behavior and actual behavior
• Relevant logs or screenshots with secrets removed

Use the feature request template for ideas. Never report security vulnerabilities in a public issue; follow SECURITY.md instead.

License

By contributing, you agree that your contributions are licensed under the MIT License.