<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added environment variable handling and logging interception for
improved script execution visibility.
* **Bug Fixes**
* Enhanced error handling with structured error responses and logs.
* **Chores**
* Updated dependencies: arktype and react-dom.
* Improved temporary work directory management and cleanup process.
* Optimized script execution model for better performance.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!--
ONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR changes the default development ports for several background
services to avoid conflicts. PostgreSQL moves from port `5432` to
`8128`, Inbucket SMTP from `2500` to `8129`, Inbucket POP3 from `1100`
to `8130`, and the OpenTelemetry collector from `4318` to `8131`. All
references across configuration files, Docker Compose setups,
environment files, CI/CD workflows, test files, and documentation have
been updated to reflect these new port assignments. A knowledge base
document has been added to document the new port mappings.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
| --- | --- |
| 1 | `claude/CLAUDE-KNOWLEDGE.md` |
| 2 | `apps/dev-launchpad/public/index.html` |
| 3 | `docker/dependencies/docker.compose.yaml` |
| 4 | `docker/emulator/docker.compose.yaml` |
| 5 | `apps/backend/.env` |
| 6 | `apps/backend/.env.development` |
| 7 | `docker/server/.env.example` |
| 8 | `package.json` |
| 9 | `.devcontainer/devcontainer.json` |
| 10 | `apps/e2e/.env.development` |
| 11 | `.github/workflows/check-prisma-migrations.yaml` |
| 12 | `.github/workflows/docker-server-test.yaml` |
| 13 | `.github/workflows/e2e-api-tests.yaml` |
| 14 | `.github/workflows/e2e-source-of-truth-api-tests.yaml` |
| 15 | `.github/workflows/restart-dev-and-test.yaml` |
| 16 |
`apps/e2e/tests/backend/endpoints/api/v1/internal/email-drafts.test.ts`
|
| 17 | `apps/e2e/tests/backend/endpoints/api/v1/internal/email.test.ts`
|
| 18 | `apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts` |
| 19 |
`apps/e2e/tests/backend/endpoints/api/v1/unsubscribe-link.test.ts` |
| 20 | `apps/e2e/tests/backend/workflows.test.ts` |
| 21 | `docs/templates/others/self-host.mdx` |
</details>
[](https://discord.gg/n3SsVDAW6U)
[
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> This PR introduces customizable development ports using
`NEXT_PUBLIC_STACK_PORT_PREFIX`, updating configurations, documentation,
and tests accordingly.
>
> - **Behavior**:
> - Default development ports for services are now customizable via
`NEXT_PUBLIC_STACK_PORT_PREFIX`.
> - PostgreSQL port changed from `5432` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}28`.
> - Inbucket SMTP port changed from `2500` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}29`.
> - Inbucket POP3 port changed from `1100` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}30`.
> - OpenTelemetry collector port changed from `4318` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}31`.
> - **Configuration**:
> - Updated `docker.compose.yaml` to use new port variables for services
like PostgreSQL, Inbucket, and OpenTelemetry.
> - Environment files in `apps/backend`, `apps/dashboard`, and
`apps/e2e` updated to use `NEXT_PUBLIC_STACK_PORT_PREFIX`.
> - `package.json` scripts updated to reflect new port configurations.
> - **Documentation**:
> - Added `CLAUDE-KNOWLEDGE.md` to document new port mappings.
> - Updated `self-host.mdx` to reflect new port configurations.
> - **Testing**:
> - Updated test files in `apps/e2e/tests` to use new port
configurations.
> - Added `helpers/ports.ts` for port-related utilities in tests.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 76ef55f58f. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **New Features**
- Enable configurable development ports via a
NEXT_PUBLIC_STACK_PORT_PREFIX, allowing parallel local environments with
custom port prefixes.
- **Bug Fixes**
- Updated local service port mappings and CI/workflow settings so
tooling and tests use the new prefixed ports consistently.
- **Documentation**
- Added docs and contributor guidance for running multiple parallel
workspaces with custom port prefixes.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: N2D4 <N2D4@users.noreply.github.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Add `STACK_FREESTYLE_API_KEY` to environment variables and update
documentation for email functionality.
>
> - **Environment Variables**:
> - Add `STACK_FREESTYLE_API_KEY` to `docker/server/.env.example`.
> - **Documentation**:
> - Update `self-host.mdx` to require `STACK_FREESTYLE_API_KEY` for
email functionality.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for d39713a7c5. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated self-hosting instructions to mention the required
`STACK_FREESTYLE_API_KEY` environment variable for email functionality.
* **Chores**
* Added `STACK_FREESTYLE_API_KEY` to environment configuration files as
a placeholder for the necessary API key.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Introduce comprehensive payment and subscription management with
Stripe integration, including new models, API endpoints, UI components,
and extensive tests.
>
> - **Features**:
> - Add Stripe integration for payments and subscriptions in
`apps/backend/src/lib/stripe.tsx` and
`apps/backend/src/app/api/latest/integrations/stripe/webhooks/route.tsx`.
> - Implement payment offers and items management in
`apps/backend/src/app/api/latest/payments`.
> - Add UI components for payment management in
`apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments`.
> - **Models**:
> - Add `Subscription` model in `prisma/schema.prisma` and
`prisma/migrations/20250805195319_subscriptions/migration.sql`.
> - **Tests**:
> - Add end-to-end tests for payment APIs in
`apps/e2e/tests/backend/endpoints/api/v1/payments`.
> - **Configuration**:
> - Update environment variables in `.env.development` and
`docker.compose.yaml` for Stripe.
> - **Misc**:
> - Add new known errors related to payments in `known-errors.tsx`.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 972c24854f. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Introduced comprehensive payments and subscriptions management with
Stripe integration.
* Added UI for managing payment offers, items, and purchase URLs in the
dashboard.
* Implemented Stripe onboarding, purchase sessions, and return flow
handling.
* Added Stripe Connect and Elements integration with theme-aware UI
components.
* **Bug Fixes**
* Enhanced validation and error handling for payments APIs and
customer/item type consistency.
* **Tests**
* Added extensive end-to-end and backend tests for payments and
purchase-related endpoints.
* **Chores**
* Updated environment variables and dependencies for Stripe support.
* Added Stripe mock service to development Docker Compose.
* **Documentation**
* Extended schemas and types for payment offers, prices, items, and
customer types.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konstantin Wohlwend <n2d4xc@gmail.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Enhances email sending API with template support, improved error
handling, and new interfaces, while adding comprehensive tests and
updating rendering logic.
>
> - **Behavior**:
> - Adds support for sending emails using templates with variables and
optional theming in `send-email/route.tsx`.
> - Introduces per-user notification category checks before sending
emails.
> - Adds optional unsubscribe link in email themes.
> - **Error Handling**:
> - Refines error handling in `send-email/route.tsx` for missing
content, non-existent user IDs, and shared email server configurations.
> - Uses `KnownErrors` for specific error cases.
> - **API Changes**:
> - Adds new interfaces and methods for email sending in
`server-interface.ts` and `admin-interface.ts`.
> - Removes deprecated email sending methods from admin interfaces.
> - **Testing**:
> - Adds e2e tests in `email.test.ts` for various email sending
scenarios, including HTML content, templates, and error cases.
> - **Misc**:
> - Updates email rendering logic in `email-rendering.tsx` to handle new
template and theme options.
> - Simplifies import statements and cleans up code structure across
multiple files.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 1d5a056699. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Enhanced email sending to support both raw HTML and template-based
emails with variables and optional theming.
* Added per-user notification category checks before sending emails.
* Email themes now support an optional unsubscribe link in the footer.
* **Improvements**
* Updated email rendering to pass the unsubscribe link as a prop to
themes.
* Refined error handling for email sending.
* Improved flexibility of email sending options and result reporting.
* **API Changes**
* Introduced new interfaces and methods for sending emails on the server
side, including detailed result reporting.
* Removed deprecated admin-side email sending methods and interfaces.
* Added new types for email sending options and results.
* **Bug Fixes**
* Fixed navigation and property naming inconsistencies in dashboard
email template editing and sending flows.
* **Chores**
* Simplified import statements and cleaned up internal code structure.
* Updated Docker environment for freestyle mock service to use Bun
runtime and adjusted port mappings.
* **Tests**
* Added comprehensive tests covering email sending scenarios, including
error handling and multi-user support.
* Updated existing tests to reflect refined email subjects, template
rendering, and unsubscribe link features.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
Note for deployment: This PR needs to add some env vars
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Adds S3-compatible storage for profile images with S3Mock for local
development, updating environment variables, Docker configurations, and
tests.
>
> - **Behavior**:
> - Adds S3-compatible storage for user, team, and team member profile
images using `uploadAndGetUrl()` in `s3.tsx`.
> - Integrates S3Mock for local development in `docker.compose.yaml` and
`emulator/docker.compose.yaml`.
> - Updates `crud.tsx` files for `users`, `teams`, and
`team-member-profiles` to use S3 for profile images.
> - **Environment**:
> - Adds S3-related environment variables to `.env.development`.
> - Updates `package.json` to include `@aws-sdk/client-s3`.
> - **Testing**:
> - Modifies test cases in `teams.test.ts` and `users.test.ts` to
validate S3 URL behavior.
> - Updates `auto-migration.tests.ts` for concurrent migration handling.
> - **Documentation**:
> - Updates `self-host.mdx` to include S3 storage requirements.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 901f0b56cd. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added support for uploading and storing user, team, and team member
profile images using S3-compatible storage.
* Integrated S3Mock for local development and testing of storage
features.
* Added new services to Docker Compose configurations for S3Mock and
related dependencies.
* Introduced image validation and processing for base64-encoded images
before upload.
* **Bug Fixes**
* Profile image upload now returns a storage URL instead of echoing back
the base64 data.
* **Documentation**
* Updated self-hosting documentation to include S3 storage requirements
and usage.
* **Chores**
* Added and updated environment variables for S3 storage configuration.
* Updated backend dependencies to include the AWS S3 SDK.
* Enhanced test cases to validate new image upload and URL behaviors.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Introduces an automated database migration system, replacing manual
Prisma commands with new scripts and updating workflows, configurations,
and tests accordingly.
>
> - **Auto-Migration System**:
> - Introduces `db-migrations.ts` script for handling database
migrations automatically.
> - Adds utility functions in `utils.tsx` for managing migration files.
> - Implements `applyMigrations` and `runMigrationNeeded` in `index.tsx`
for executing migrations.
> - **Workflow and Scripts**:
> - Updates GitHub workflows (`check-prisma-migrations.yaml`,
`e2e-api-tests.yaml`) to use new migration commands.
> - Replaces `prisma migrate` commands with `db:init`, `db:migrate`,
etc., in `package.json` and `README.md`.
> - **Testing**:
> - Adds `auto-migration.tests.ts` for testing migration logic and
concurrency handling.
> - **Configuration**:
> - Updates `.env.development` and `vitest.config.ts` for new
environment variables and paths.
> - Modifies `turbo.json` and `package.json` to include new migration
tasks and scripts.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 2c24183879. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Fix Docker restart by processing environment variables in a temporary
working directory in `entrypoint.sh`.
>
> - **Behavior**:
> - Create `/tmp/processed` directory in `entrypoint.sh` to copy and
process files for environment variable replacement.
> - Replace environment variable sentinels in files within
`/tmp/processed` instead of `/app`.
> - Change working directory to `/tmp/processed` before starting backend
and dashboard.
> - **Misc**:
> - Add logging for file copying to working directory in
`entrypoint.sh`.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for bb6ff27e90. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Enable Docker build by removing fail step and switch from `bcrypt` to
`bcryptjs` for password hashing.
>
> - **Docker Workflow**:
> - Removed temporary fail step in
`.github/workflows/docker-server-build.yaml` to enable Docker build
process.
> - **Dependencies**:
> - Replaced `bcrypt` with `bcryptjs` in `package.json` and `hashes.tsx`
for password hashing.
> - Updated `@types/bcrypt` to `@types/bcryptjs` in `package.json`.
> - **Documentation**:
> - Added `docker/README.md` with instructions for building and running
Docker containers for server and emulator.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for c7a3ed9f11. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Port dashboard to Next.js 15, update dependencies, and enhance Docker
workflows.
>
> - **Next.js 15 Migration**:
> - Update `next` to `15.2.3` in `apps/backend/package.json`,
`apps/dashboard/package.json`, and `examples/demo/package.json`.
> - Remove MDX support in `next.config.mjs`.
> - Use `turbopack` in `dev` scripts in `apps/dashboard/package.json`
and `examples/demo/package.json`.
> - **Docker Workflows**:
> - Add `docker-emulator-test.yaml` for testing Docker emulator.
> - Rename `docker-build.yaml` to `docker-server-build.yaml` and
`docker-test.yaml` to `docker-server-test.yaml`.
> - Update `docker-compose.yaml` for emulator setup.
> - **Code Refactoring**:
> - Convert several `Page` components to async functions in
`apps/dashboard/src/app`.
> - Use `dynamic` import for `react-globe.gl` in `globe.tsx`.
> - Remove `experimental` config in `next.config.mjs`.
> - **Dependency Updates**:
> - Update `react` and `react-dom` to `19.0.0` in
`apps/backend/package.json`, `apps/dashboard/package.json`, and
`examples/demo/package.json`.
> - Add `pnpm` overrides for `@types/react` and `@types/react-dom` in
multiple `package.json` files.
> - **Miscellaneous**:
> - Add `docker/readme.md` for Docker instructions.
> - Update `entrypoint.sh` for Docker server setup.
> - Remove `globals.d.ts` as it's empty.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 5f5d8fd65c. It will automatically
update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
---------
Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>
Co-authored-by: Zai Shi <zaishi00@outlook.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Introduces a new Model Context Protocol server with OpenAPI
integration, updates build configurations, and adds necessary files for
initial release.
>
> - **New MCP Server**:
> - Implements MCP server in `src/index.ts` using
`@modelcontextprotocol/sdk`.
> - Handles tool requests with `ListToolsRequestSchema` and
`CallToolRequestSchema`.
> - Supports 40 endpoints, defined in `operationIDs`.
> - **OpenAPI Integration**:
> - Generates OpenAPI schema in `generate-openapi.ts` and writes to
`mcp-server/openapi`.
> - Converts OpenAPI parameters to JSON schema in
`openapi-to-jsonschema.ts`.
> - **Configuration and Build**:
> - Adds `package.json` for MCP server with dependencies and scripts.
> - Configures ESLint in `.eslintrc.cjs`.
> - Updates `Dockerfile` and `turbo.json` to include MCP server in build
process.
> - **Miscellaneous**:
> - Adds `.gitignore` for OpenAPI JSON files.
> - Initial release noted in `CHANGELOG.md`.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for d0970c4059. It will automatically
update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
