Advanced Installation

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.

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

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.

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, make these provider decisions explicit:

• which providers stay enabled
• which provider has 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 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.

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 advanced installations, INTERACTIVE is still the safer default unless you intentionally want a more automatic flow. 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. 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
  password: ""
  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.

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

8. Replace default routing targets with real ones

Open settings and align routing with the backend targets 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.

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

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

connection:
  routing:
    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

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

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