Merge pull request #869 from karrioapi/karrio-preview-2025.5rc23

Karrio preview 2025.5rc23

Author: danh91

.env.grafana-test

@@ -5,9 +5,10 @@
 # Core Server Settings
 DEBUG_MODE=True
 ADMIN_DASHBOARD=True
-ALLOWED_HOSTS=*,localhost,127.0.0.1
+ALLOWED_HOSTS=*,localhost,127.0.0.1,api.karrio.local,app.karrio.local,karrio.local
 SECRET_KEY="n*s-ex6@ex_r1i%bk=3jd)p+lsick5bi*90!mbk7rc3iy_op1r"
 USE_HTTPS=False
+CSRF_TRUSTED_ORIGINS=http://localhost:5002,https://api.karrio.local,https://app.karrio.local
 
 # Database Configuration (SQLite for Development)
 DATABASE_NAME=db.sqlite3
@@ -34,10 +35,10 @@ WORK_DIR=.karrio
 OIDC_RSA_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n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\n-----END RSA PRIVATE KEY-----"
 
 # Email Configuration (Optional)
-# EMAIL_PORT=1025
-# EMAIL_USE_TLS=false
-# EMAIL_HOST=maildev
-# EMAIL_HOST_USER=admin@example.com
+EMAIL_PORT=1025
+EMAIL_USE_TLS=false
+EMAIL_HOST=localhost
+EMAIL_HOST_USER=admin@example.com
 
 # Redis Configuration (Optional)
 # REDIS_HOST=localhost

.env.sample

@@ -16,10 +16,7 @@ jobs:
       - uses: actions/checkout@v2
       - name: Checkout submodules
         run: |
-          git submodule sync --recursive
-          git submodule update --init --recursive || true
-          # Continue even if some submodules fail due to permissions
-          git submodule foreach --recursive 'git submodule update --init || true'
+          git submodule update --init community
       - name: Run Tests
         run: |
           ./bin/setup-sdk-env -v &&
@@ -37,10 +34,7 @@ jobs:
       - uses: actions/checkout@v2
       - name: Checkout submodules
         run: |
-          git submodule sync --recursive
-          git submodule update --init --recursive || true
-          # Continue even if some submodules fail due to permissions
-          git submodule foreach --recursive 'git submodule update --init || true'
+          git submodule update --init community
       - name: Run Tests
         env:
           ENABLE_ALL_PLUGINS_BY_DEFAULT: true
@@ -57,10 +51,7 @@ jobs:
       - uses: actions/checkout@v2
       - name: Checkout submodules
         run: |
-          git submodule sync --recursive
-          git submodule update --init --recursive || true
-          # Continue even if some submodules fail due to permissions
-          git submodule foreach --recursive 'git submodule update --init || true'
+          git submodule update --init community
       - uses: actions/setup-node@v3
         with:
           node-version: 22.x

.github/workflows/tests.yml

@@ -0,0 +1,30 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- Runtime apps live under `apps/`: `apps/api` hosts the Django service, `apps/dashboard` and `apps/web` power the Next.js UIs, and `apps/www` serves public marketing pages.
+- Shared Python code is grouped in `modules/` (core logic, connectors, pricing, etc.), while shared TypeScript utilities live in `packages/`; carrier extensions live in `plugins/` and community-maintained variants sit in `community/`.
+- Automation scripts live in `bin/`, and container workflows use the manifests in `docker/` alongside `docker-compose.yml`.
+
+## Build, Test, and Development Commands
+- Bootstrap once with `./bin/setup-dev-env` to create the Python virtualenv and install common tooling.
+- Run `./bin/start-dev` to launch the API (port 5002) and dashboard (port 3002); `npm run dev -w @karrio/dashboard` targets the dashboard alone, and `docker compose up` inside `docker/` brings up the full stack.
+- Front-end builds flow through Turbo: `npm run build` executes `turbo run build`, and `npm run lint` fans out ESLint across all workspaces.
+
+## Coding Style & Naming Conventions
+- Python follows PEP 8 with 4-space indentation—format via `black` and keep typing clean with `mypy` (both listed in `requirements.dev.txt`).
+- Use snake_case for modules/functions (e.g., `modules/pricing/rate.py`) and PascalCase for classes; mirror existing mapper naming in `modules/connectors`.
+- TypeScript and React code are formatted with Prettier (`npm run format`) and linted through `packages/eslint-config-custom`; prefer 2-space indentation and explicit exports.
+
+## Testing Guidelines
+- Activate the environment with `source bin/activate-env` before invoking tests.
+- Run `./bin/run-server-tests` for the API suites; carrier adapters must stay on Python's `unittest` with canonical files like `test_rate.py` and classes shaped as `Test<Carrier><Feature>`.
+- Validate connectors via `python -m unittest discover -v -f modules/connectors/<carrier>/tests`, and guard SDK changes with `./bin/run-sdk-tests`; include the debug prints and tuple assertions mandated in `CARRIER_INTEGRATION_GUIDE.md`.
+
+## Commit & Pull Request Guidelines
+- Keep commits focused and follow the short `type: summary` style already used (`fix:`, `feat:`, `chore:`); reference issues with `refs #123` or `fixes #123`.
+- Rebase on `main`, rerun lint/test commands, and attach screenshots or CLI transcripts whenever behaviour changes.
+- Fill out the PR template, link discussions, enable "Allow edits from maintainers," and list the verification steps reviewers can replay.
+
+## Configuration Tips
+- Workspace-specific `.env` files drive local overrides; duplicate provided templates and never commit secrets.
+- Use `./bin/create-new-env` when you need a fresh sample configuration, and load additional variables through Docker compose overrides or CI secrets to keep builds reproducible.

AGENTS.md

@@ -1,3 +1,26 @@
+# Karrio 2025.5rc23
+
+## Changes
+
+### Feat
+
+- feat: adds a button to copy docs pages for LLMs
+
+### Fix
+
+- fix: redirection issue when signin page is accessed directly
+- fix: the readability of certain features on the documentation when in dark mode
+
+### Chore
+
+- chore: set up Posthog for docs analytics
+
+### DevX
+
+- devx: prevent node constant override to latest version and set a minimum version for karrio development
+- devx: debugging and improving dev and HTTPS support both for development and production deployment
+- devx: introduce AGENTS.md using cursor
+
 # Karrio 2025.5rc22
 
 ## Changes

CHANGELOG.md

@@ -109,6 +109,7 @@ We <3 contributions big and small. In priority order (although everything is app
 
 -   Ask general question on [Github Discussions](https://github.com/orgs/karrioapi/discussions)
 -   Submit a [feature request](https://github.com/orgs/karrioapi/discussions)
+-   Review the [Repository Guidelines](AGENTS.md) for project-specific conventions
 -   Open a PR (see our instructions on [developing Karrio locally](https://docs.karrio.io/contributing/development))
 
 ### Contributors

README.md

@@ -1 +1 @@
-2025.5rc22
+2025.5rc23

apps/api/karrio/server/VERSION

@@ -0,0 +1,48 @@
+# =============================================================================
+# KARRIO DASHBOARD CONFIGURATION - HTTPS LOCAL DEVELOPMENT
+# =============================================================================
+
+# Core Dashboard Settings
+NEXT_PUBLIC_DASHBOARD_VERSION=2025.X
+
+# =============================================================================
+# SERVER INTEGRATION
+# =============================================================================
+
+# Karrio API Server Configuration - HTTPS Local Domains
+KARRIO_URL=https://api.karrio.local
+NEXT_PUBLIC_KARRIO_PUBLIC_URL=https://api.karrio.local
+
+# =============================================================================
+# AUTHENTICATION CONFIGURATION
+# =============================================================================
+
+# Next.js Authentication Settings - HTTPS Local Domains
+AUTH_TRUST_HOST=true
+NEXTAUTH_URL=https://app.karrio.local
+NEXTAUTH_SECRET="n*s-ex6@ex_r1i%bk=3jd)p+lsick5bi*90!mbk7rc3iy_op1r"
+JWT_APP_SECRET_KEY="n*s-ex6@ex_r1i%bk=3jd)p+lsick5bi*90!mbk7rc3iy_op1r"
+
+# =============================================================================
+# MULTI-TENANCY CONFIGURATION
+# =============================================================================
+
+# Multi-tenant Settings (Enterprise)
+NEXT_PUBLIC_MULTI_TENANT=false
+KARRIO_ADMIN_API_KEY=XXX
+
+# =============================================================================
+# THIRD-PARTY INTEGRATIONS
+# =============================================================================
+
+# Address Autocomplete Service
+NEXT_PUBLIC_ADDRESS_AUTO_COMPLETE_SERVICE=google # values: canadapost, google
+NEXT_PUBLIC_ADDRESS_AUTO_COMPLETE_SERVICE_KEY=xxxxxxxxxxx
+
+# =============================================================================
+# ERROR TRACKING & MONITORING
+# =============================================================================
+
+# Sentry Configuration
+# NEXT_PUBLIC_SENTRY_DSN=https://xxxxx
+SENTRY_IGNORE_API_RESOLUTION_ERROR=1

apps/dashboard/.env.https

@@ -1,5 +1,5 @@
 # =============================================================================
-# KARRIO DASHBOARD CONFIGURATION
+# KARRIO DASHBOARD CONFIGURATION - LOCAL DEVELOPMENT
 # =============================================================================
 
 # Core Dashboard Settings
@@ -9,15 +9,15 @@ NEXT_PUBLIC_DASHBOARD_VERSION=2025.X
 # SERVER INTEGRATION
 # =============================================================================
 
-# Karrio API Server Configuration
-# KARRIO_URL=http://localhost:5002
+# Karrio API Server Configuration - Localhost
+KARRIO_URL=http://localhost:5002
 NEXT_PUBLIC_KARRIO_PUBLIC_URL=http://localhost:5002
 
 # =============================================================================
 # AUTHENTICATION CONFIGURATION
 # =============================================================================
 
-# Next.js Authentication Settings
+# Next.js Authentication Settings - Localhost
 AUTH_TRUST_HOST=true
 NEXTAUTH_URL=http://localhost:3002
 NEXTAUTH_SECRET="n*s-ex6@ex_r1i%bk=3jd)p+lsick5bi*90!mbk7rc3iy_op1r"

apps/dashboard/.env.sample

@@ -3,7 +3,6 @@ import { withSentryConfig } from "@sentry/nextjs";
 import { readdirSync, statSync } from "fs";
 import { fileURLToPath } from "url";
 import path from "path";
-
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const BASE_PATH = process.env.NEXT_PUBLIC_BASE_PATH || "";