Skip to content
Skip to content
Get started
/Developers

Developers

Contributing

How to set up zcrypt locally, the conventions the project follows, and how to submit a change.

Overview

zcrypt is a zero-knowledge encrypted cloud storage system, and this page mirrors the repository's CONTRIBUTING.md. Because it's a security/cryptography product, read docs/SECURITY.md before reporting anything that might be a vulnerability. Report it privately through GitHub's private vulnerability reporting (the repository's Security tab), and do not open a public issue for security problems.

Prerequisites

  • •Go 1.26+
  • •Node.js 20+ and Bun
  • •PostgreSQL (or a free Neon database)
  • •Docker (optional)

Local setup

Backend

shell
cd app/backend

# Create your own environment file from the template, then fill in real values.
cp .env.example .env
# At minimum set DATABASE_URL, MASTER_KEY, and ZCRYPT_JWT_SECRET.
# Generate keys with: openssl rand -hex 32

go build -o zcrypt-server .
go test ./...
go vet ./...

./zcrypt-server

Frontend

shell
cd app/frontend

bun install
echo "NEXT_PUBLIC_API_URL=http://localhost:8080" > .env.local

bun run dev        # dev server
bun run build      # production build
bun run lint       # lint
bun run typecheck  # type check

Environment variables

Never commit a real .env; it is gitignored. The backend template lives at app/backend/.env.example. Copy it to .env and supply your own values. Each contributor is responsible for their own credentials. If you accidentally commit a secret, rotate it immediately and let a maintainer know.

Coding conventions

  • •Backend. Standard Go. stdlib net/http (no web framework). Wrap errors with fmt.Errorf("context: %w", err). UUID primary keys. Raw SQL via pgxpool (no ORM). Run go vet ./... and go test ./... before pushing.
  • •Frontend. TypeScript + React 19. "use client" for interactive components. Zustand for global state, Tailwind for styling, Hugeicons for icons. No emojis in code. Run bun run lint and bun run typecheck before pushing.
  • •Commits. Keep them focused and write clear messages.

Quality gate

Before pushing, run the change-scoped quality gate. It runs typecheck, lint, tests, and build for whichever modules you touched (frontend / backend / core / desktop), mirroring CI:

shell
bash scripts/install-hooks.sh          # once per clone, wires the pre-push hook
bash scripts/prepush.sh --gates-only   # fast: gates only
bash scripts/prepush.sh                # full: gates + advisory backlog scans -> docs/report.md

The pre-push hook runs this for you

Once installed, the pre-push hook runs the gates automatically on git push; bypass a single push with git push --no-verify if you must.

Branch and PR conventions

  • •Fork the repository (or create a feature branch if you have write access). Do not commit directly to main.
  • •Use a descriptive branch name, e.g. feat/repo-rotation, fix/cors-whitelist, or docs/readme.
  • •Make your change with tests where it makes sense, and ensure the build, lint, type check, and tests pass.
  • •Open a pull request against main with a clear description of what changed and why. Link any related issue.
  • •A maintainer will review. Address feedback by pushing additional commits to the same branch.

License

By contributing to zcrypt, you agree that your contributions will be licensed under the MIT License, the same license that covers the project.

Full source and issue tracker: github.com/Wosmos/zcrypt.