Normal Installation

Download the artifacts

Place the runtime and provider jars

plugins/
├── Identica-BUNDLE-<version>.jar
└── identica/
    └── providers/
        ├── Identica-Credential-<version>.jar
        └── Identica-Premium-<version>.jar

plugins/
├── Identica-VELOCITY-<version>.jar
└── identica/
    └── providers/
        ├── Identica-Credential-<version>.jar
        └── Identica-Premium-<version>.jar

Start the runtime once and stop it again

Start the platform once so Identica can create its initial files and folders. This first boot is only meant to let the plugin prepare its default configuration layout. You are not expected to finish setup on this first start.

If everything is fine, Identica will print its welcome message or banner after startup finishes.

Once that first boot has completed and the files were created, stop the proxy cleanly before editing the generated configuration.

This page stays procedural on purpose. The detailed meaning of each config area belongs in Configuration.

Enable and order the providers

Open the generated providers/providers config and keep the generated structure as your base. In most cases, the defaults are already close to what you want.

For typical mixed setups, it makes sense for premium to have a higher priority than credential. In practice, that means if Identica has to choose between those providers for the same player or entrypoint situation, premium wins before credential. That is the behavior most users expect.

For the first pass, the important decisions are:

• which providers stay enabled
• which provider gets higher priority
• whether entrypoint hostnames should map directly to a provider

A practical starting point looks like this:

behavior:
  attemptTtl: 10m

providers:
  - id: premium
    displayName: "PR"
    enabled: true
    priority: 200
    entrypoints:
      - premium.example.com

  - id: credential
    displayName: "CR"
    enabled: true
    priority: 100
    entrypoints:
      - credential.example.com

Most installations can leave the top-level behavior values alone on the first pass.

If you are not using hostname-based routing yet, leave entrypoints empty or replace the default values later when you know the real hostnames. Keep the generated verification blocks unless verification setup is intentionally part of this installation pass.

Understand journey mode and journey policy

The generated engine config also includes journeyMode and journeyPolicy.

• SEAMLESS means a step is expected to continue without player interaction
• INTERACTIVE means the step may prompt the player, wait for input, or otherwise require explicit interaction

For most installations, INTERACTIVE is the easier and safer choice because the player can clearly see what Identica expects from them. Typical interactive behavior includes things like entering a credential, choosing a provider, confirming a verification code, or responding to a migration prompt.

In the current setup described by these guides, INTERACTIVE can also produce a better first impression. If you leave the flow on SEAMLESS, a player who joins from an offline account while using a premium username may hit the higher-priority premium provider first and get an invalid-session-style kick from the server on that first join. That can scare users away before they understand what happened, even if a second rejoin would work.

With INTERACTIVE, the player can enter the enrollment step instead and choose the provider directly. If you want less manual selection in that flow, the generated engine.scenarios.registration settings also include autoSelectSingleProvider, which you can enable for scenarios where only one provider should be chosen automatically.

journeyPolicy controls how strictly the selected mode should be applied:

• PREFER means Identica tries to use the configured mode first, but may fall back to another viable mode if needed
• STRICT means Identica should only use the configured mode

For most setups, PREFER is the better default.

Replace default routing targets with a simple real route

The generated routing defaults use example routing targets. Do not leave them unchanged unless those names really exist in your environment.

It is usually not a good idea to use the same target for both step routing and completion routing. In most cases, step targets should point to an authentication or transition destination, while completion should point to the place where the player is actually meant to end up.

defaults:
  step:
    target: lobby
  complete:
    target: lobby

Review security and refine the setup

Do not stop at the first successful startup. After the baseline works, walk through the generated configuration and the rest of the docs so you understand what the plugin will do in your network.

Some defaults are intentionally strict. For example, credential requirements may be stronger than what your players are used to, so review them before treating the setup as final.

Get help or report issues

If you find a bug, need support, or want a feature, we are happy to help:

• GitHub issues and pull requests
• Discord

Critical fixes are usually handled quickly. Less critical improvements may be prioritized later.