The product & documentation site
Plain HTML, CSS, JavaScript, and screenshots. No application server, database, or build step.
Static hosting instructions ↓A home for your site.
A foundation for your CRM.
Two different deployments, clearly explained. Publish the product site as static files, or run the application with its required services.
What are you deploying?
Publish this website.
Preview the folder.
From the repository root, run this local preview command, then open http://localhost:8082.
python -m http.server 8082 --bind 127.0.0.1 --directory website/v2Upload the website contents.
Copy the contents of
website/v2/into your static host’s document root or publish directory. Include all four HTML pages, the CSS/JS files, and the entire assets folder. No install or build command is needed.Configure the entry point.
Serve
index.htmlat your site root. Keepdocs.html,hosting.html, andscreenshots.htmlreachable directly. Relative asset links also support publishing under a subdirectory. No single-page-app fallback is required.Connect your domain.
Use your host’s domain and HTTPS configuration. Once DNS resolves, verify the homepage, direct documentation links, screenshots, and mobile navigation over HTTPS.
Publish only
website/v2/. The repository root contains application code and configuration that do not belong in a public static document root. Python’s server is for local preview.Static host settings
| Setting | Value |
|---|---|
| Site / publish directory | website/v2 from the repository root |
| Framework preset | Static / none |
| Build command | None |
| Entry document | index.html |
| Secrets or environment | None for this website |
Prepare the CRM environment.
The repository’s deployment template targets an Ubuntu VPS with a reverse proxy and PM2. Plan for a compatible Node.js runtime, pnpm 10, MySQL, protected persistent storage, and a domain with HTTPS.
HTTPS / domainReverse proxy
Web · 3650Next.js staff application
API · 4000Express → MySQL
Letters · 3001Optional separate workspace
These are the defaults in ecosystem.config.cjs. Plan the enabled services before starting processes: the ecosystem file also includes a separate Compassion service, which is outside this donor CRM setup.
Make configuration explicit.
Create a protected production environment file based on .env.example. Replace example secrets and stale version metadata. Do not publish or commit the populated file.
| Configuration | Purpose |
|---|---|
DATABASE_URL | Production MySQL connection with appropriate application access |
JWT_SECRET | Strong, private authentication secret |
CREDENTIAL_ENCRYPTION_KEY | Persistent encryption key for configured credentials; preserve with protected backups |
FRONTEND_ORIGIN | Exact HTTPS browser origin allowed by the API |
NEXT_PUBLIC_APP_URL | Public HTTPS app URL |
NEXT_PUBLIC_API_URL | Public API base URL for the deployment’s routing |
PORT / API_PORT | Web and API listening ports |
| SMTP and optional integrations | Configure only enabled workflows and verify credentials separately |
NEXT_PUBLIC_* values are browser-visible and can be baked into the web build. Never put secrets in them. Export the production environment before migrations, generation, builds, and process startup; the API’s dotenv loader does not automatically select .env.production.
Prepare a controlled release.
Use an authorized checkout of the intended revision. Back up the database and persistent files before applying migrations, and verify that you can restore them. This Bash sequence assumes a protected, shell-compatible .env.production file.
set -euo pipefail
set -a
source .env.production
set +a
pnpm install --frozen-lockfile
pnpm db:generate
pnpm typecheck
pnpm lint
pnpm test:unit
pnpm test:api
pnpm build
pnpm build:server
# Apply reviewed migrations in your release window.
pnpm db:migrate
# Start only the donor web and API services.
pnpm exec pm2 start ecosystem.config.cjs --only oyama-crm-web,oyama-crm-api --env production --update-envFor an existing installation, restart the selected existing processes with the updated environment after a successful build. Run pnpm exec pm2 save after verifying the process list, and configure your server’s PM2 startup integration for reboot persistence.
Adding the separate Letters workspace
If enabled, run pnpm build:letters, configure its API origin and reverse-proxy routing, and start oyama-letters explicitly. Do not start unrelated services simply because they appear in the ecosystem file.
This is a repository-based deployment guide, not a claim that a fresh production deployment has been exercised. Review the production-readiness checklist and validate your actual environment before onboarding staff.
Connect the public URL to the services.
The existing VPS template routes web traffic to port 3650 and API traffic to port 4000. Preserve the /api prefix when proxying to Express, and forward host and HTTPS information. Review any web-owned API routes and optional workspace routing for your enabled features.
Keep upstream services and the database off the public internet where possible. Terminate HTTPS at your proxy, use the exact production origin, and leave permissive development CORS disabled.
Review the full proxy template ↗Verify the release. Keep it healthy.
- Check PM2 process state and logs; verify the web URL and
/api/health. - Sign in using the intended staff role and verify permissions with a restricted account.
- Check constituents, donations, fiscal period selection, and a representative report.
- Validate enabled email, letters, uploads, and public links in a controlled test.
- Monitor application errors, storage, database availability, and backups.
- Keep the previous release and a tested recovery plan; schema rollback may require database recovery rather than only reverting code.