Skip to main content

Installation

This page adds the Aivie.Content package to an existing Umbraco 17 site. Connecting Aivie to OpenAI follows in Get Started.

Requirements​

  • Umbraco 17.5.0 or later. This is the version Aivie itself is built against. Use 17.6.0 or later if you can: on earlier versions a known Umbraco issue can make the Aivie licence unreadable. Aivie then stays viewable but stops creating and changing anything until the licence can be read again.
  • .NET 10.
  • SQL Server or SQLite as the Umbraco database. Aivie creates its own tables in it and needs no separate connection string.
  • An OpenAI API key. You enter it in the setup wizard.

Umbraco.AI and Umbraco.Community.JobsJobsJobs (which runs the background jobs) are installed automatically as dependencies. You do not need to add them yourself.

Install via .NET CLI​

Run the commands from the folder of your web project. The order matters.

dotnet add package HtmlSanitizer --version 9.1.973
dotnet add package Aivie.Content

HtmlSanitizer has to be on version 9.1.973 or newer before you add Aivie. Older versions pin AngleSharp to exactly 0.17.1, while Umbraco.AI needs AngleSharp 1.4 or newer, and NuGet cannot raise a package reference in your own project for you. Without this step the restore fails with error NU1107. Do not follow the advice in that error message to add AngleSharp directly, because that makes it worse. See Install and restore errors if you run into it.

Nothing else in your site needs to change. Aivie registers itself through composers, so there is no AddAivie() call to add to Program.cs. If you have one from an earlier version, it does nothing and you can remove it.

Pin Data Protection​

This step is optional, but strongly recommended. Add the following to Program.cs, replacing YourProject with a name for your site:

// At the top of the file; without this using the compiler does not know SetApplicationName and
// PersistKeysToFileSystem (CS1061).
using Microsoft.AspNetCore.DataProtection;

// Pin Data Protection.
//
// Without this, .NET stores the key ring in the profile of the account the site runs under, and
// derives the application discriminator from the content root path. Encrypted values become
// unreadable as soon as the app pool runs under a different account, the profile is not loaded, or
// the folder is moved.
//
// Umbraco.AI stores a connection's API key this way. If it can no longer be decrypted, the backoffice
// shows the raw value and encrypts it again on save - after which the connection is permanently
// broken. The same key ring protects login sessions and OpenIddict tokens.
//
// The folder belongs in your backups and must not be cleaned up. With multiple servers this must be a
// shared location.
builder.Services
    .AddDataProtection()
    .SetApplicationName("YourProject")
    .PersistKeysToFileSystem(
        new DirectoryInfo(Path.Combine(
            builder.Environment.ContentRootPath, "umbraco", "Data", "DataProtection-Keys")));

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddComposers()
    .Build();

WebApplication app = builder.Build();
warning

Without a pinned key ring, an API key stored directly in an Umbraco.AI connection can become unreadable after you move the site or the app pool starts running under a different account. The connection is then permanently broken until you enter the key again. Include the key folder in your backups, and use a shared location when you run more than one server. If this already happened, see API key unreadable.

What happens on first start​

Start the site and open the backoffice. On the first start Aivie prepares the following by itself:

  1. Database tables. Aivie creates the tables it needs in the Umbraco database. All of them have the prefix aivie_.

  2. User groups. Aivie creates three groups under Users → User Groups, if they do not exist yet:

    GroupAccessMembers at creation
    Aivie-adminThe Aivie sectionThe Umbraco administrators, once
    AivieThe Aivie sectionNone
    Umbraco AIThe AI section of Umbraco.AI (agents, contexts, profiles)None

    Aivie-admin is the group that may install and configure Aivie. An Umbraco administrator who is not in this group does not get Setup, Settings or Licence. They do see General, Datasources, Chat suggestions and Keyword actions, next to the screens for everyday use. The other two groups start empty, so you add the right people yourself. Aivie never changes the members of an existing group on a later start. See Roles and access.

  3. Access for the Umbraco Administrators group. If no user group has access to the Aivie section yet, Aivie gives that access to the Umbraco Administrators group, once. This happens before the three groups above are created. If a group already has access, Aivie leaves it as it is.

  4. The Aivie section. The section appears in the backoffice as Aivie - Content. Until the setup is finished, its welcome screen says that setup is not finished yet and offers a Go to setup button. Only members of Aivie-admin see that note.

  5. A description field for images. Aivie adds the field AI Omschrijving to the Image media type, unless that type already has a description field. See Image descriptions.

When you log in as a member of Aivie-admin before the setup is finished, a dialog titled Aivie is not set up yet appears once per browser. Choose Go to setup to open the setup wizard, or Later to dismiss it. The next step is the setup wizard.

Updating Aivie​

Update the package to the newest version and restart the site:

dotnet add package Aivie.Content

That is all an update needs. On start, Aivie brings its default instruction layers up to date where you did not change them, adds default layers that are new in this version, and lists the layers you did change under Newer default layers in Setup, so that you decide per layer. See Default layers.

Existing agents keep their instructions, because they are often tuned per site. On start, Aivie only replaces a few known sentences from earlier default instructions with their current wording. A sentence you rewrote yourself is not found and stays as it is. If a new version changes the instruction text in other ways, update it yourself under AI → Agents → Instructions.

Restore defaults is not part of an update​

You do not need Restore defaults after an update. The button in Setup, under Restore default layout, serves another purpose and is a deliberate choice: it puts the Aivie contexts, and which contexts and surfaces each agent has, back to the standard of the installed version. It also replaces the layer texts in those contexts by the defaults. That is destructive: manual changes to the Aivie contexts, the agent links or the surfaces in AI → Contexts and AI → Agents are reset, and this cannot be undone. Your datasources, your customer-specific context, your own resources of other types, the instructions of the agents and the files in the context folder are kept.

It makes sense when someone changed the contexts, agent links or surfaces by hand and you want the standard back, or when the site was set up with an older version and you want the layout of the installed version. See Restore the default layout.