{"id":46982878,"url":"https://github.com/zextras/carbonio-admin-console-ui","last_synced_at":"2026-05-04T13:03:05.010Z","repository":{"id":342330677,"uuid":"468308305","full_name":"zextras/carbonio-admin-console-ui","owner":"zextras","description":"Admin Console UI for Carbonio","archived":false,"fork":false,"pushed_at":"2026-05-01T02:52:42.000Z","size":15273,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":2,"default_branch":"devel","last_synced_at":"2026-05-01T04:19:36.388Z","etag":null,"topics":["carbonio","carbonio-component","carbonio-ui","collaboration","collaboration-suite","email","email-server","oss"],"latest_commit_sha":null,"homepage":"https://zextras.com/carbonio","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zextras.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2022-03-10T11:10:15.000Z","updated_at":"2026-04-30T09:14:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"a9ef9800-559f-4957-ae69-ef9d6ba73a91","html_url":"https://github.com/zextras/carbonio-admin-console-ui","commit_stats":null,"previous_names":["zextras/carbonio-admin-console-ui"],"tags_count":130,"template":false,"template_full_name":null,"purl":"pkg:github/zextras/carbonio-admin-console-ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zextras%2Fcarbonio-admin-console-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zextras%2Fcarbonio-admin-console-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zextras%2Fcarbonio-admin-console-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zextras%2Fcarbonio-admin-console-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zextras","download_url":"https://codeload.github.com/zextras/carbonio-admin-console-ui/tar.gz/refs/heads/devel","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zextras%2Fcarbonio-admin-console-ui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32608311,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"ssl_error","status_checked_at":"2026-05-04T10:08:02.005Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["carbonio","carbonio-component","carbonio-ui","collaboration","collaboration-suite","email","email-server","oss"],"created_at":"2026-03-11T13:22:43.056Z","updated_at":"2026-05-04T13:03:05.003Z","avatar_url":"https://github.com/zextras.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Carbonio Admin UI Monorepo\n\nCarbonio Admin Console UI is the web-based administrative interface for [Zextras Carbonio](https://www.zextras.com/carbonio/), providing domain management, backup, storage, MTA configuration, and other administrative capabilities through a micro-frontend architecture.\n\nIt is organized as a monorepo of 12 admin modules and shared packages, managed with pnpm workspaces and Turborepo.\n\n## Quick Start\n\n### Prerequisites\n\n- **Node.js** \u003e= 22.14.0\n- **pnpm** 10.15.0\n\n### Building\n\n```bash\n# Install dependencies\npnpm install\n\n# Build all applications\npnpm build\n\n# Start the dev server\npnpm dev\n```\n\nTo build the distributable packages (deb/rpm) using [YAP](https://github.com/m0rf30/yap) in a container:\n\n```bash\nmake build                         # Build JS apps and package for Ubuntu 22.04\nmake build TARGET=ubuntu-noble     # Build for Ubuntu 24.04\nmake build TARGET=rocky-9          # Build for Rocky Linux 9\n```\n\nOther available `make` targets (run `make help` for the full list):\n\n| Target            | Description                                          |\n| ----------------- | ---------------------------------------------------- |\n| `make install`    | Install all dependencies                             |\n| `make build-dev`  | Build JS apps in development mode, without packaging |\n| `make test`       | Run tests                                            |\n| `make lint`       | Run ESLint and TypeScript type checks                |\n| `make clean`      | Remove build artifacts and cache                     |\n| `make reset`      | Full clean reinstall                                 |\n| `make deploy`     | Deploy to `TEST_HOST` defined in `.env`              |\n| `make deploy-dev` | Deploy development build to `TEST_HOST`              |\n\n## Installation\n\nThis package is distributed as part of the [Carbonio platform](https://zextras.com/carbonio). To install:\n\n### Ubuntu (Jammy/Noble)\n\n```bash\napt-get install carbonio-admin-console-ui\n```\n\n### Rocky Linux (8/9)\n\n```bash\nyum install carbonio-admin-console-ui\n```\n\n## Development Server\n\n### Starting the Dev Server\n\nTo start the development server, run:\n\n```bash\npnpm dev\n```\n\nThe dev server will start on `http://localhost:3000/carbonioAdmin/`.\n\n### Configuring Proxy Target\n\nBy default, the dev server proxies API requests to `https://localhost:6071`. To change the proxy target, set the `VITE_TARGET` environment variable:\n\n```bash\n# Use a custom hostname\nVITE_TARGET=myserver pnpm dev\n\n# The proxy target will be set to: https://myserver:6071\n```\n\nAll proxy endpoints (`/service`, `/services`, `/zx`, `/logout`, `/carbonioAdmin/static`, `/static/login`) will forward requests to the configured target.\n\n## Available Scripts\n\nAll scripts use Turborepo for efficient task orchestration across workspaces.\n\n### Building\n\n```bash\npnpm build      # Build all applications in dependency order\npnpm build:dev  # Build in development mode (no cache)\n```\n\n`pnpm build`:\n\n- Builds the shell application (admin-ui-bootstrap)\n- Builds all admin modules\n- Generates the unified package structure in `/dist/` directory\n- Creates import maps and component manifests\n\n### Deployment\n\n```bash\npnpm run deploy \u003chostname\u003e      # Build and deploy to a remote host\npnpm run deploy:dev \u003chostname\u003e  # Deploy development build\n```\n\nThe deploy script:\n\n- Runs `pnpm build`\n- Creates .deb packages using YAP\n- Uploads the package to the remote host\n- Installs the package via apt\n\n### Testing\n\n```bash\npnpm test     # Run tests once across all packages\npnpm test:ci  # Run tests with coverage reporting (CI mode)\n```\n\n### Code Quality\n\n```bash\npnpm type-check  # TypeScript type checking\npnpm lint        # Run ESLint\npnpm lint:fix    # Auto-fix ESLint issues\npnpm type-lint   # Type check + lint combined\n```\n\n### Working with Individual Apps\n\n```bash\n# Run tests for a specific app\npnpm --filter @zextras/admin-ui-domains test\n```\n\n## Workspace Management\n\n### Understanding Workspaces\n\nThis monorepo uses pnpm workspaces to manage multiple packages:\n\n- **`apps/*`** - Standalone applications (12 admin modules)\n- **`packages/*`** - Shared packages used across apps\n\n### Workspace Dependencies\n\nPackages reference each other using the `workspace:*` protocol:\n\n```json\n{\n  \"dependencies\": {\n    \"@zextras/ui-shared\": \"workspace:*\",\n    \"@zextras/ui-components\": \"workspace:*\"\n  }\n}\n```\n\nThis ensures you're always using the local version during development.\n\n### Adding Dependencies\n\n```bash\n# Add a dependency to a specific workspace\npnpm add \u003cpackage\u003e --filter \u003cappname\u003e\n\n# Add a dev dependency to root\npnpm add -D \u003cpackage\u003e -w\n\n# Add a dependency to all workspaces\npnpm add \u003cpackage\u003e -r\n```\n\n## Architecture\n\n### Module System\n\nThe admin console uses a micro-frontend architecture:\n\n1. **Shell** (`admin-ui-bootstrap`) - Provides the runtime environment, routing, and shared state\n1. **Modules** (other apps) - Independent features loaded dynamically by the shell\n1. **Shared Dependencies** - Vendored common libraries (React, tanstack-query , etc.) loaded once as a singleton\n\n### Import Maps\n\nThe build system generates import maps to resolve module dependencies:\n\n```json\n{\n  \"imports\": {\n    \"react\": \"/static/iris/shared-dependencies/{commit}/index.mjs\"\n  }\n}\n```\n\nThis enables:\n\n- Shared dependency vendoring (React, tanstack-query, loaded once)\n- Version stability through commit-based URLs\n- Independent module deployment\n\n### Module Loading Order\n\nModules are loaded based on their `priority` value defined in each app's `package.json`:\n\n- **Shell (priority: -1)** - Always loads first\n- **Admin modules (priority: 3)** - Load in parallel after shell\n\n## Workspace Structure\n\n### Applications (apps/)\n\nThe monorepo contains 12 applications organized as:\n\n```text\napps/\n├── admin-ui-bootstrap/      # Shell application (priority: -1)\n├── admin-ui-dashboard/      # Dashboard overview (priority: 3)\n├── admin-ui-domains/        # Domain management (priority: 3)\n├── admin-ui-backup/         # Backup management (priority: 3)\n├── admin-ui-cos/            # Cloud object storage (priority: 3)\n├── admin-ui-legalhold/      # Legal hold management (priority: 3)\n├── admin-ui-mta/            # Mail transfer agent (priority: 3)\n├── admin-ui-notifications/  # Notifications management (priority: 3)\n├── admin-ui-operations/     # Operations console (priority: 3)\n├── admin-ui-privacy/        # Privacy management (priority: 3)\n├── admin-ui-storage/        # Storage management (priority: 3)\n└── admin-ui-subscription/   # Subscription management (priority: 3)\n```\n\n### Packages (packages/)\n\n```text\npackages/\n├── ui-components/    # @zextras/ui-components - Shared UI component library\n└── test-utils/       # admin-ui-test-utils - Testing utilities and mocks\n```\n\n## Testing Guide\n\n### Testing Framework\n\nThis monorepo uses **Vitest** with **@vitest/browser** for browser-based testing:\n\n- **Unit tests** - Test pure functions, hooks, and utilities in Node.js\n- **Browser tests** - Test React components with real DOM using Playwright\n- **MSW** - Mock Service Worker for API mocking\n\n### Running Tests\n\n#### Local Development\n\n```bash\n# Run tests once across all packages\npnpm test\n\n# Run tests in watch mode with browser preview\ncd apps/admin-ui-domains\npnpm test:watch\n```\n\nThe `test:watch` command opens a browser with the Vitest UI for interactive testing.\n\n#### CI Environment\n\n```bash\n# Run tests with coverage reporting\npnpm test:ci\n```\n\n#### Visible Browser Mode\n\nTo run browser tests with a visible browser window (useful for debugging):\n\n```bash\npnpm test:headed\n```\n\n## Development Guidelines\n\n### Commit Message Format\n\nFollow the **commitizen** convention:\n\n```text\n\u003ctype\u003e(\u003cscope\u003e): \u003cdescription\u003e\n\n[optional body]\n\n[optional footer]\n```\n\n**Types:**\n\n- `feat` - New features (use sparingly, only for user-visible changes)\n- `fix` - Bug fixes\n- `chore` - Maintenance tasks\n- `docs` - Documentation changes\n- `style` - Formatting changes\n- `test` - Test additions/modifications\n- `refactor` - Code restructuring (use sparingly, only for \u003e6 files)\n\n**Scope Format:**\n\n- Root changes: `[root]`\n- Monorepo app: `[app-name]`\n- Specific file: `(filename)` after type\n\n**Examples:**\n\n```text\nfeat[admin-ui-domains](domain-list): add pagination controls\nfix[admin-ui-bootstrap](auth): resolve token refresh race condition\nchore[root](pnpm-lock): update @types/react to 19.2.11\n```\n\n**Content Rules:**\n\n- Keep title under 50 characters\n- Wrap body at 72 characters\n- Stay factual and humble\n- Focus on what changed, not why\n\n## Troubleshooting\n\n### Dependency Issues\n\nIf you encounter dependency-related errors:\n\n```bash\npnpm reset\n```\n\nThis cleans all caches and reinstalls dependencies from scratch.\n\n### Build Failures\n\nIf builds fail unexpectedly:\n\n1. **Clear Turbo cache:**\n\n   ```bash\n   rm -rf .turbo\n   ```\n\n1. **Clean and reinstall:**\n\n   ```bash\n   pnpm reset\n   ```\n\n1. **Check Node.js version:**\n\n   ```bash\n   node --version  # Should be \u003e=22.14.0\n   ```\n\n### Test Timeout Issues\n\nIf tests timeout or hang:\n\n1. **Use timeout command:**\n\n   ```bash\n   timeout 120 pnpm test\n   ```\n\n1. **Check for `test.only` or `it.only`:**\n\n   - Never remove `.only` from tests\n   - These indicate tests currently under development\n\n1. **Verify browser availability:**\n\n   ```bash\n   pnpm exec playwright install chromium\n   ```\n\n### Module Resolution Problems\n\nIf imports fail to resolve:\n\n1. **Verify workspace protocol:**\n\n   ```json\n   {\n     \"dependencies\": {\n       \"@zextras/ui-components\": \"workspace:*\"\n     }\n   }\n   ```\n\n1. **Clean and reinstall:**\n\n   ```bash\n   rm -rf node_modules pnpm-lock.yaml\n   pnpm install\n   ```\n\n1. **Check TypeScript paths in tsconfig.json**\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for information on how to contribute to this project.\n\n## License\n\nThis project is licensed under the GNU Affero General Public License v3.0 - see the [LICENSE.md](LICENSE.md) file for details.\n\nThis project follows the [REUSE specification](https://reuse.software/) for license management. The full license text is also available at `LICENSES/AGPL-3.0-only.txt`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzextras%2Fcarbonio-admin-console-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzextras%2Fcarbonio-admin-console-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzextras%2Fcarbonio-admin-console-ui/lists"}