Advanced Installation

Installation path for setups where state should survive restarts or be shared across runtimes.

Use this path when you want Identica state to survive runtime restarts while TTLs are still valid, or when more than one runtime should share the same replicated state. This is the right path for restart continuity, shared state between runtimes, deliberate routing, and environments that need a stable multi-runtime operating model. In the current implementation, that shared state is provided through Redis.

Scope

This guide covers the advanced installation needs around shared state, restart continuity, and routing. 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

the server running Identica must be able to connect to Redis
you want sessions and pending pipeline state to survive restarts or be shared between runtimes
you are ready to keep shared-state names stable for the environment
you know the real backend targets the runtime should route players to

This guide does not require a multi-proxy deployment. Replication is still useful on a single runtime when restart continuity matters.

If multiple runtimes will share the same replicated state, keep them on the same Identica version and give each one its own unique serverId.

Installation steps

Download the artifacts

Use GitHub releases when you want stable published versions.

Download flow:

Open the releases page.
Open the release version you want to install.
Expand the release assets if they are collapsed.
Choose one installation style:

download Identica-BUNDLE-<version>.jar if you want one runtime jar that can run on either supported proxy platform
download Identica-PLATFORMS-<version>.zip if you want the platform-specific runtime jars instead
also download Identica-Credential-<version>.jar
also download Identica-Premium-<version>.jar

You do not need the API jar for a normal installation.

Place the runtime and provider jars

You can install Velocity in either of these ways:

Use Identica-BUNDLE-<version>.jar as the runtime jar.
Use the platform-specific runtime jar from Identica-PLATFORMS-<version>.zip.

Bundle placement flow:

Copy Identica-BUNDLE-<version>.jar into plugins/.
Create plugins/identica/ if it does not exist yet.
Create plugins/identica/providers/ if it does not exist yet.
Copy Identica-Credential-<version>.jar into plugins/identica/providers/.
Copy Identica-Premium-<version>.jar into plugins/identica/providers/.

Bundle layout:

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

Platform-specific placement flow:

Extract Identica-PLATFORMS-<version>.zip.
Copy Identica-VELOCITY-<version>.jar into plugins/.
Create plugins/identica/ if it does not exist yet.
Create plugins/identica/providers/ if it does not exist yet.
Copy Identica-Credential-<version>.jar into plugins/identica/providers/.
Copy Identica-Premium-<version>.jar into plugins/identica/providers/.

Before starting the proxy, double-check these placement rules:

the bundle jar belongs in plugins/ and replaces the platform-specific runtime jar only
the platform-specific runtime jar belongs in plugins/
provider jars belong in plugins/identica/providers/
provider jars should not be placed directly in the root plugins/ folder

Platform-specific layout:

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 before you begin the shared-state setup.

First startup can look stuck

On the first startup, Identica downloads its required libraries, so the server may not print anything new for a while and can feel stuck even though the download is still in progress. This can be fast or slow depending on the internet connection, and the server must have internet access and be able to reach Cloudflare-protected sites.

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.

On this first start, the main goal is to let Velocity load the runtime jar and let Identica prepare its config directory.

Review these generated locations after the first boot:

plugins/identica/settings
plugins/identica/engine
plugins/identica/routing
plugins/identica/messages
plugins/identica/commands
plugins/identica/features/sentinel/settings
plugins/identica/features/sentinel/messages
plugins/identica/features/verification/settings
plugins/identica/persistence
plugins/identica/replication
plugins/identica/providers/conflicts
plugins/identica/providers/capabilities
plugins/identica/providers/providers

The current default boot path creates a configuration marker with type=YAML.

It is safe to stop the proxy after these files exist.

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 hostname-based routing is not part of this rollout yet, leave entrypoints empty or replace the default values later when you know the real hostnames.

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.

Turn shared state into an intentional environment contract

Open the generated replication config and change it from generated defaults into a stable environment definition.

The two most important rules are:

enabled must be true
serverId must become a stable value you chose on purpose, not the generated random default

A practical starting point looks like this:

enabled: true
serverId: velocity-main

redis:
  host: redis.internal
  port: 6379
  credential: ""
  ssl: false
  timeout: 5000

If a second runtime should share this replicated environment, keep the same Redis connection details, channel names, and cache namespaces, but give that runtime a different serverId, for example velocity-fallback.

Keep channels and cache namespaces stable

Once an environment starts using replicated state, treat these names as part of its contract:

redis.channels.*
cache.*

That stability is what lets sessions, reservations, attempts, and pending pipeline state stay coherent across restarts and across multiple runtimes.

Do not casually rename those keys after the environment is live. If you need environment-specific naming, decide it before the rollout and then keep it stable.

Replace default routing targets with real ones

Open routing and align targets with the backend names that actually exist. The default values are examples only.

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.

In Velocity, these target values are backend server names from your proxy configuration.

If you want, you can still balance those requests across multiple backend servers, but that is not a feature of Identica itself. Identica only asks Velocity to route a player to the target you configured.

Load balancing or target rewriting belongs to an external plugin. For example, a balancer plugin such as PlayerBalancer can intercept a request for auth-1 and redirect the player to another server such as auth-3 according to its own rules.

For a segmented topology, a good baseline looks like this:

defaults:
  step:
    target: auth
  complete:
    target: lobby
scenarios:
  registration:
    step:
      target: registration
  migration:
    step:
      target: migration

Use your real server names, not the names shown here. Generated routing config leaves scenarios empty; add scenario entries only when a scenario needs to differ from defaults. If one step needs exceptional routing, use a step override instead of changing the whole scenario:

scenarios:
  registration:
    overrides:
      steps:
        your-step-id:
          target: auth

That keeps the normal scenario route stable while still letting one specific step land somewhere else.

If you want something closer to a real advanced setup, you can also configure retries and more specific targets. A practical example looks like this:

defaults:
  step:
    target: auth
    attempts:
      mode: RETRY_ONCE
      maxAttempts: 2
      retryDelay: 1s
      consumeOnReached: false
      consumeOnExhausted: true
  complete:
    target: lobby
    attempts:
      mode: NONE
      maxAttempts: 1
      retryDelay: 0s
      consumeOnReached: true
      consumeOnExhausted: true
scenarios:
  registration:
    step:
      target: register
      attempts:
        mode: RETRY_ONCE
        maxAttempts: 2
        retryDelay: 1s
        consumeOnReached: false
        consumeOnExhausted: true
    complete:
      target: lobby
    overrides:
      steps:
        provider-selection:
          target: register-fallback
  migration:
    step:
      target: migrate
      attempts:
        mode: RETRY_ONCE
        maxAttempts: 3
        retryDelay: 2s
        consumeOnReached: false
        consumeOnExhausted: true
    complete:
      target: survival

In that example:

authentication, registration, and migration each use their own step target
completion sends the player to the place they should end up after the flow is done
retries are enabled for step routing where temporary target issues are more likely
one registration step is overridden to a different server without changing the whole scenario

Use this kind of setup when different parts of the flow really do belong on different backend servers. If your network is simpler, keep the routing simpler too.

If your hosting panel limits how many separate backend servers you can run, a lightweight limbo server can help. One example is PicoLimbo, which can run with Velocity and gives you a virtual routing destination hosted through the proxy side instead of requiring another full gameplay server.

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.

Protect the authentication flow

Because Identica is an identity plugin, it does not try to own every command or routing behavior on the server. That is why it is strongly recommended to use a command filter or blocker for commands that could let players escape the authentication flow before they finish it.

Examples of dangerous behavior can include:

switching servers before authentication is complete
using commands that move the player into the real server environment too early
reaching systems that should only be available after authentication

Many networks handle that with a separate blocker or filter plugin. Identica does not treat that as core identity-plugin functionality.

Get help or report issues

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

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

Advanced Installation

On this page