From fec55754f4902bec151545207e3b598af7dd711e Mon Sep 17 00:00:00 2001 From: Andrey Sobolev Date: Wed, 8 Oct 2025 23:28:24 +0700 Subject: [PATCH] Create README.md --- README.md | 232 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000000..9bb3420a7e --- /dev/null +++ b/README.md @@ -0,0 +1,232 @@ +# Huly Server + +[![GitHub License](https://img.shields.io/github/license/hcengineering/huly.server?style=for-the-badge)](LICENSE) + +⭐️ Your star shines on us. Star us on GitHub! + +## About + +Huly Server is a collection of server-side packages extracted from the [Huly Platform](https://github.com/hcengineering/platform). This repository contains backend infrastructure components, storage adapters, and server-side utilities that power the Huly ecosystem. + +These packages provide essential server-side functionality including database adapters (MongoDB, PostgreSQL, Elasticsearch), storage providers (MinIO, S3), messaging infrastructure (Kafka), and collaborative editing capabilities. They are designed to be modular, scalable, and production-ready for building robust backend services. + +## Packages + +This repository includes the following server packages: + +### Server Core + +- [@hcengineering/server-core](packages/core) - Core server infrastructure, adapters, storage management, and server-side utilities +- [@hcengineering/server](packages/server) - Main server implementation and runtime +- [@hcengineering/server-client](packages/client) - Server-side client implementation for inter-service communication +- [@hcengineering/middleware](packages/middleware) - Server middleware components and request processing + +### Database Adapters + +- [@hcengineering/mongo](packages/mongo) - MongoDB adapter for document storage +- [@hcengineering/postgres](packages/postgres) - PostgreSQL adapter for relational data +- [@hcengineering/elastic](packages/elastic) - Elasticsearch adapter for full-text search and analytics + +### Storage Providers + +- [@hcengineering/server-storage](packages/server-storage) - Storage abstraction layer and implementations +- [@hcengineering/minio](packages/minio) - MinIO storage provider for object storage +- [@hcengineering/s3](packages/s3) - AWS S3 compatible storage provider +- [@hcengineering/datalake](packages/datalake) - Data lake storage and management + +### Infrastructure + +- [@hcengineering/kafka](packages/kafka) - Apache Kafka integration for event streaming and messaging +- [@hcengineering/collaboration](packages/collaboration) - Real-time collaborative editing infrastructure + +## Pre-requisites + +Before proceeding, ensure that your system meets the following requirements: + +- [Node.js](https://nodejs.org/en/download/) (v20.11.0 or higher is required) +- [Rush](https://rushjs.io/) - Microsoft's scalable monorepo manager +- [Docker](https://docs.docker.com/get-docker/) - For running development services +- [Docker Compose](https://docs.docker.com/compose/install/) - For orchestrating development environment + +## Verification + +To verify the installation, perform the following checks in your terminal: + +- Ensure that the `docker` commands are available: + +```bash +docker --version +docker compose version +``` + +- Verify Node.js version: + +```bash +node --version +``` + +## Installation + +You need Microsoft's [rush](https://rushjs.io/) to install the application. + +1. Install Rush globally using the command: + + ```bash + npm install -g @microsoft/rush + ``` + +1. Navigate to the repository root and run the following commands: + + ```bash + rush install + rush build + ``` + +## Build + +To build all packages: + +```bash +rush build +``` + +To rebuild (ignoring cache): + +```bash +rush rebuild +``` + +## Build & Watch + +For development purposes, `rush build:watch` action could be used: + +```bash +rush build:watch +``` + +It includes build and validate phases in watch mode. + +## Update project structure + +If the project's structure is updated, it may be necessary to relink and rebuild the projects: + +```bash +rush update +rush build +``` + +## Troubleshooting + +If a build fails, but the code is correct, try to delete the [build cache](https://rushjs.io/pages/maintainer/build_cache/) and retry: + +```bash +rm -rf common/temp/build-cache +rush rebuild +``` + +## Tests + +To execute all tests: + +```bash +rush test +``` + +For individual test execution inside a package directory: + +```bash +rushx test +``` + +### Running Integration Tests + +The repository includes integration tests that require Docker services: + +```bash +cd tests +./prepare-tests.sh +rush test +``` + +### Test Coverage + +To generate test coverage reports: + +```bash +# Run tests with coverage +rush test + +# Merge coverage reports from all packages +node common/scripts/merge-coverage.js + +# Generate HTML coverage report +node common/scripts/generate-coverage-html.js + +# View coverage summary +sh common/scripts/show-coverage-summary.sh +``` + +The coverage report will be available in `coverage/html/index.html`. + +## Package Publishing + +To bump a package version: + +```bash +node ./common/scripts/bump.js -p projectName +``` + +## Development Environment + +### Setting Up Services + +The repository includes a Docker Compose configuration for development services: + +```bash +cd tests +docker compose up -d +``` + +This will start: + +- MongoDB - Document database +- PostgreSQL - Relational database +- Elasticsearch - Search engine +- MinIO - Object storage +- Kafka - Message broker + +### Environment Variables + +Create a `.env` file in the `tests` directory with the following variables: + +```env +MONGO_URL=mongodb://localhost:27017 +POSTGRES_URL=postgresql://localhost:5432/huly +ELASTIC_URL=http://localhost:9200 +MINIO_ENDPOINT=localhost +MINIO_PORT=9000 +KAFKA_BROKERS=localhost:9092 +``` + +## Related Projects + +- [Huly Platform](https://github.com/hcengineering/platform) - The main Huly Platform repository +- [Huly Core](https://github.com/hcengineering/huly.core) - Core packages and client libraries +- [Huly Self-Host](https://github.com/hcengineering/huly-selfhost) - Self-hosting solution for Huly +- [Huly Examples](https://github.com/hcengineering/huly-examples) - API usage examples + +## Contributing + +Contributions are welcome! Please feel free to submit a Pull Request. + +## License + +Licensed under the [EPL-2.0](LICENSE) license. + +## Additional Links + +- [Huly Website](https://huly.io/) +- [Documentation](https://docs.huly.io/) +- [Community](https://github.com/hcengineering/platform/discussions) + +© 2025 [Hardcore Engineering Inc](https://hardcoreeng.com/).