Getting Started

Technical Manual

This is the Technical Manual, for developers and IT staff who install, configure, deploy and extend the modules. If you use the app in the browser, go to the User Manual instead.

Use this repository when you want the Orchard Core host applications, Orchard-specific modules, or the Orchard documentation site. For shared framework guidance, see core.crestapps.com.

Prerequisites

• .NET 10 SDK
• Node.js for the asset pipeline
• Network access to:
  • https://api.nuget.org/v3/index.json
  • https://nuget.cloudsmith.io/orchardcore/preview/v3/index.json
  • https://nuget.cloudsmith.io/crestapps/crestapps-core/v3/index.json

Install packages in your Orchard solution

Install all CrestApps Orchard modules

dotnet add package CrestApps.OrchardCore.Cms.Core.Targets

Install individual modules

dotnet add package CrestApps.OrchardCore.AI
dotnet add package CrestApps.OrchardCore.AI.Chat
dotnet add package CrestApps.OrchardCore.OpenAI

After installing packages, enable the required features in Tools -> Features inside the Orchard admin.

Modules that need connection strings, API keys or tuning values read them from appsettings.json, environment variables or a secret store. The Configuration Reference lists every section, the environment-variable form of each key, and which source wins when a value is set in more than one place.

Release notes

Review the current Version 3.0.0 Release Notes before updating package references or tenant code. They list the breaking changes since the 2.x line.

The repository currently builds the 3.0.0 line on .NET 10 against Orchard Core 4.0.x preview packages. The published 2.1.x line is the latest stable release; its documentation is available from the version picker.

Build this repository locally

git clone https://github.com/CrestApps/CrestApps.OrchardCore.git
cd CrestApps.OrchardCore
npm install
npm run rebuild
dotnet build .\CrestApps.OrchardCore.slnx -c Release

Dependency vulnerability auditing is enabled for every build and a published advisory fails it. If the build stops on an NU1901-NU1904 error, pin the patched version in Directory.Packages.props rather than disabling the audit.

The .NET build depends on Orchard Core preview packages. If Cloudsmith is unreachable, asset builds still work but the .NET restore/build will not.

The asset build needs Node.js 24, the version pinned in .node-version. npm install at the repository root installs the packages of every module, and npm run rebuild builds each module's Assets.json with Vite. See Building Front-End Assets for the commands, the Assets.json format, and how to add a script or a library to a module.

Run the startup apps

CMS host

cd .\src\Startup\CrestApps.OrchardCore.Cms.Web
dotnet run

Use this app when you want to test modules inside a full Orchard Core site.

Aspire host

cd .\src\Startup\CrestApps.Aspire.AppHost
dotnet run

Use this when you want the local orchestration environment for the sample clients and supporting services.

The Aspire host starts Ollama, Redis, a PostgreSQL container running the pgvector image, and an Elasticsearch container. PostgreSQL provides a local vector store, and Elasticsearch backs the Orchard Core search indexes.

Both stores keep their data under src\Startup\CrestApps.OrchardCore.Cms.Web\App_Data, mounted into the containers instead of Docker volumes, so they sit beside the rest of the tenant data:

Container	Data folder	Host port
PostgreSQL (pgvector)	App_Data\PostgreSQL	5432
Elasticsearch	App_Data\Elasticsearch	9200

The app host creates both folders on startup, and the first run initializes the data there. Delete a folder's contents to start that store over.

The credentials are app host parameters, so they can be overridden through user secrets:

cd .\src\Startup\CrestApps.Aspire.AppHost
dotnet user-secrets set Parameters:PostgresPassword "<password>"
dotnet user-secrets set Parameters:ElasticsearchPassword "<password>"

PostgreSQL defaults to postgres/postgres with a vectordb database, and Elasticsearch to the built-in elastic user with the password elasticsearch.

The host passes both connections to the CMS as environment variables, so features pick them up without any per-feature setup:

OrchardCore__CrestApps__PostgreSQL__ConnectionString
OrchardCore__CrestApps__Elasticsearch__Url
OrchardCore__CrestApps__Elasticsearch__Username
OrchardCore__CrestApps__Elasticsearch__Password
OrchardCore__OrchardCore_Elasticsearch__*

The CrestApps sections are the global connections described in AI Data Sources - PostgreSQL and AI Data Sources - Elasticsearch. For everything else the app host sets, see Local development with Aspire. The OrchardCore_Elasticsearch section configures the Orchard Core Elasticsearch feature that owns the Orchard-managed indexes.

Share the local stores

Because the data lives in App_Data, sharing that folder shares the vector store and the indexes with it. Stop the Aspire host first so both containers shut down cleanly, then copy or zip App_Data; copying the files while the containers run produces torn data. The other developer drops the folder into their own CrestApps.OrchardCore.Cms.Web and starts the app host, which mounts it as is.

Leave App_Data\logs out of the copy. It holds the site logs rather than any state, and it grows to gigabytes on a long-running development site.

Each store is only readable by the major version that wrote it, so both sides must stay on the images pinned by the app host. Both must also use the same passwords, since PostgreSQL bakes its credentials into the cluster when it is first initialized.

To move individual databases instead of the whole folder, run pg_dump and pg_restore inside the container:

docker exec -e PGPASSWORD=postgres <container> pg_dump --username postgres --dbname vectordb --format=custom --file /tmp/vectordb.dump
docker cp <container>:/tmp/vectordb.dump .\vectordb.dump

To work against shared servers instead of copies, host them somewhere both developers can reach and set the connections per developer rather than in source control. The CMS project does not declare a user secrets ID, so run dotnet user-secrets init once first. User secrets are only read when ASPNETCORE_ENVIRONMENT is Development:

cd .\src\Startup\CrestApps.OrchardCore.Cms.Web
dotnet user-secrets init
dotnet user-secrets set OrchardCore:CrestApps:PostgreSQL:ConnectionString "<connection string>"
dotnet user-secrets set OrchardCore:CrestApps:Elasticsearch:Url "<url>"

Sample clients

cd .\src\Startup\CrestApps.OrchardCore.Samples.McpClient
dotnet run

cd .\src\Startup\CrestApps.OrchardCore.Samples.A2AClient
dotnet run

Build the docs site

cd .\src\CrestApps.Docs
npm install
npm run build

Package feeds

• Stable packages: NuGet.org
• Shared Core preview feed: Cloudsmith CrestApps Core feed
• Shared Core preview source URL: https://nuget.cloudsmith.io/crestapps/crestapps-core/v3/index.json
• Orchard Core preview source URL: https://nuget.cloudsmith.io/orchardcore/preview/v3/index.json