Normal Installation

Use this path when you want to use Identica on a simple Minecraft server setup without shared restart-surviving state. It is meant for straightforward usage, simple routing, and normal day-to-day operation where cache and pending journey state do not need to survive plugin restarts.

Scope

This guide covers the basic installation needs most users expect from existing authentication plugins. Use the Providers overview to see the full set of providers you can install and use. Those broader provider choices are not covered by this installation page.

What this path assumes

• one Identica runtime is enough
• you want a simple setup instead of a replicated environment
• sessions, cache, and pending journey state do not need to survive plugin restarts
• a simple routing layout is enough for the server or proxy

If you do need sessions and pending state to survive plugin restarts, use Advanced installation. That requires replication to be enabled.

1. Download the artifacts

2. Place the runtime and provider jars

plugins/identica/providers/

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

3. 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.

4. Enable and order the providers

Open the generated 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 password. In practice, that means if Identica has to choose between those providers for the same player or entrypoint situation, premium wins before password. 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:

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

  - id: password
    displayName: "CR"
    enabled: true
    priority: 100
    overrides: {}
    entrypoints:
      - password.example.com

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.

5. Understand journey mode and journey policy

The generated settings may also include 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 normal 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 password, choosing a provider, confirming a verification code, or responding to a migration prompt.

In the current setup described by this guide, 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 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.

6. Replace default routing targets with a simple real route

The generated settings 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.

connection:
  routing:
    defaults:
      step:
        target: lobby
      complete:
        target: lobby

8. 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, password requirements may be stronger than what your players are used to, so review them before treating the setup as final.

9. 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.