Config Server

The Config Server is an advanced feature designed for large deployments managing multiple Lavalink instances. For single-server deployments, use the application.yml file instead.

The Lavalink Config Server allows you to manage the configuration of multiple Lavalink servers from a centralized location, supporting both Git repositories and local filesystems as configuration backends.

Features

Centralized Management

Manage all Lavalink configurations from one location

Git Integration

Store configurations in Git for version control

Profile Support

Different configurations for different environments

Hot Reloading

Update configurations without restarting servers

Architecture

The Config Server acts as a centralized configuration provider:

┌─────────────────┐
│  Git Repository │
│       or        │  ──┐
│  Local Files    │    │
└─────────────────┘    │
                       ▼
              ┌─────────────────┐
              │  Config Server  │
              │   (Port 8888)   │
              └─────────────────┘
                       │
        ┬──────────────┼──────────────┬
        │              │              │
        ▼              ▼              ▼
  ┌──────────┐  ┌──────────┐  ┌──────────┐
  │ Lavalink │  │ Lavalink │  │ Lavalink │
  │ Server 1 │  │ Server 2 │  │ Server 3 │
  └──────────┘  └──────────┘  └──────────┘

Lavalink Client Configuration

Configure your Lavalink servers to pull configuration from the Config Server.

Using application.yml

application.yml

spring:
  config:
    import: configserver:http://localhost:8888
  cloud:
    config:
      enabled: true
      name: lavalink
      profile: default
      label: main
      fail-fast: true
      username: admin
      password: youshallnotpass

spring.config.import

string

required

URL of the Config Server in the format configserver:http://host:port.

spring.cloud.config.enabled

boolean

default:"true"

Enable Spring Cloud Config client.

spring.cloud.config.name

string

default:"lavalink"

Application name used to locate configuration files.

spring.cloud.config.profile

string

default:"default"

Configuration profile (e.g., “production”, “staging”, “development”).

spring.cloud.config.label

string

default:"main"

Git branch or label to use.

spring.cloud.config.fail-fast

boolean

default:"true"

Whether to fail startup if the Config Server is unavailable.

spring.cloud.config.username

string

Username for Config Server basic authentication.

spring.cloud.config.password

string

Password for Config Server basic authentication.

Using Environment Variables

SPRING_CONFIG_IMPORT=configserver:http://localhost:8888
SPRING_CLOUD_CONFIG_ENABLED=true
SPRING_CLOUD_CONFIG_NAME=lavalink
SPRING_CLOUD_CONFIG_PROFILE=production
SPRING_CLOUD_CONFIG_LABEL=main
SPRING_CLOUD_CONFIG_FAIL_FAST=true
SPRING_CLOUD_CONFIG_USERNAME=admin
SPRING_CLOUD_CONFIG_PASSWORD=youshallnotpass

Config Server Setup

Docker Deployment

The recommended way to run the Config Server is using Docker.

docker-compose.yml

services:
  lavalink-config-server:
    image: ghcr.io/lavalink-devs/lavalink-config-server:master
    container_name: lavalink-config-server
    restart: unless-stopped
    environment:
      # Set environment variables here
      SPRING_SECURITY_USER_NAME: admin
      SPRING_SECURITY_USER_PASSWORD: youshallnotpass
      SPRING_PROFILES_ACTIVE: native
    volumes:
      # Mount application.yml if not using environment variables
      - ./application.yml:/opt/Lavalink-Config-Server/application.yml
      # Mount config files directory for native backend
      - ./config:/opt/Lavalink-Config-Server/config
    networks:
      - lavalink
    expose:
      - 8888
    ports:
      # Only expose if accessing from outside Docker network
      - "8888:8888"
      # For localhost only:
      # - "127.0.0.1:8888:8888"

networks:
  lavalink:
    name: lavalink

Config Server Configuration

Git Backend
Native Backend

Store configurations in a Git repository:

application.yml

spring:
  security:
    enabled: true
    user:
      name: admin
      password: "youshallnotpass"
  profiles:
    active: git
  cloud:
    config:
      server:
        accept-empty: false
        git:
          uri: "https://github.com/lavalink-devs/Lavalink-Example-Configs"
          search-paths: "{application}"
          skipSslValidation: false
          timeout: 5
          cloneOnStart: true
          force-pull: false
          deleteUntrackedBranches: false
          refreshRate: 0
          # For private repositories:
          # username: trolley
          # password: ghp_token_here
          defaultLabel: main

server:
  port: 8888
  address: 0.0.0.0

logging:
  level:
    root: INFO
    org.springframework.cloud.config: DEBUG

spring.cloud.config.server.git.uri

string

required

Git repository URL. Supports placeholders: {application}, {profile}, {label}.

spring.cloud.config.server.git.search-paths

string

default:""

Subdirectories to search for config files. Use {application} to organize by app name.

spring.cloud.config.server.git.cloneOnStart

boolean

default:"false"

Clone repository on startup instead of on first request.

spring.cloud.config.server.git.defaultLabel

string

default:"main"

Default Git branch to use.

Store configurations on the local filesystem:

application.yml

spring:
  security:
    enabled: true
    user:
      name: admin
      password: "youshallnotpass"
  profiles:
    active: native
  cloud:
    config:
      server:
        accept-empty: false
        native:
          search-locations: "file:config/{application}"

server:
  port: 8888
  address: 0.0.0.0

logging:
  level:
    root: INFO
    org.springframework.cloud.config: DEBUG

spring.cloud.config.server.native.search-locations

string

required

File system paths to search. Supports placeholders: {application}, {profile}, {label}.

When using the native backend, specify the config location explicitly via spring.config.location=application.yml to prevent the Config Server from loading configs from subdirectories.

Environment Variables for Config Server

Git Backend
Native Backend

# Security
SPRING_SECURITY_ENABLED=true
SPRING_SECURITY_USER_NAME=admin
SPRING_SECURITY_USER_PASSWORD=youshallnotpass

# Profile
SPRING_PROFILES_ACTIVE=git

# Git Configuration
SPRING_CLOUD_CONFIG_SERVER_ACCEPT_EMPTY=false
SPRING_CLOUD_CONFIG_SERVER_GIT_URI=https://github.com/lavalink-devs/Lavalink-Example-Configs
SPRING_CLOUD_CONFIG_SERVER_GIT_SEARCH_PATHS={application}
SPRING_CLOUD_CONFIG_SERVER_GIT_SKIP_SSL_VALIDATION=false
SPRING_CLOUD_CONFIG_SERVER_GIT_TIMEOUT=5
SPRING_CLOUD_CONFIG_SERVER_GIT_CLONE_ON_START=true
SPRING_CLOUD_CONFIG_SERVER_GIT_FORCE_PULL=false
SPRING_CLOUD_CONFIG_SERVER_GIT_DELETE_UNTRACKED_BRANCHES=false
SPRING_CLOUD_CONFIG_SERVER_GIT_REFRESH_RATE=0
SPRING_CLOUD_CONFIG_SERVER_GIT_DEFAULT_LABEL=main

# For private repositories
# SPRING_CLOUD_CONFIG_SERVER_GIT_USERNAME=trolley
# SPRING_CLOUD_CONFIG_SERVER_GIT_PASSWORD=ghp_token_here

# Server
SERVER_PORT=8888
SERVER_ADDRESS=0.0.0.0

# Logging
LOGGING_LEVEL_ROOT=INFO
LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_CLOUD_CONFIG=DEBUG

# Security
SPRING_SECURITY_ENABLED=true
SPRING_SECURITY_USER_NAME=admin
SPRING_SECURITY_USER_PASSWORD=youshallnotpass

# Profile
SPRING_PROFILES_ACTIVE=native

# Native Configuration
SPRING_CLOUD_CONFIG_SERVER_ACCEPT_EMPTY=false
SPRING_CLOUD_CONFIG_SERVER_NATIVE_SEARCH_LOCATIONS=file:config/{application}

# Server
SERVER_PORT=8888
SERVER_ADDRESS=0.0.0.0

# Logging
LOGGING_LEVEL_ROOT=INFO
LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_CLOUD_CONFIG=DEBUG

Configuration Repository Structure

Organize your configuration files following this structure:

.
└── Lavalink/
    ├── application.yml              # Default configuration
    ├── application-production.yml   # Production profile
    ├── application-staging.yml      # Staging profile
    └── application-development.yml  # Development profile

Profile Override Behavior

Configurations are merged in this order:

application.yml (base configuration)
application-{profile}.yml (profile-specific overrides)

Example:

lavalink:
  server:
    password: "default-password"
    sources:
      youtube: false
      bandcamp: true
      soundcloud: true
    bufferDurationMs: 400

Result for production profile:

lavalink:
  server:
    password: "production-secure-password"  # Overridden
    sources:
      youtube: false        # Inherited from base
      bandcamp: true        # Inherited from base
      soundcloud: true      # Inherited from base
    bufferDurationMs: 800   # Overridden

Example Config Repository

See the Lavalink Example Configs repository for a complete example setup.

Complete Deployment Example

docker-compose.yml

version: '3.8'

services:
  # Config Server
  config-server:
    image: ghcr.io/lavalink-devs/lavalink-config-server:master
    container_name: lavalink-config-server
    restart: unless-stopped
    environment:
      SPRING_SECURITY_USER_NAME: admin
      SPRING_SECURITY_USER_PASSWORD: youshallnotpass
      SPRING_PROFILES_ACTIVE: git
      SPRING_CLOUD_CONFIG_SERVER_GIT_URI: https://github.com/your-org/lavalink-configs
      SPRING_CLOUD_CONFIG_SERVER_GIT_DEFAULT_LABEL: main
      SPRING_CLOUD_CONFIG_SERVER_GIT_CLONE_ON_START: true
    networks:
      - lavalink
    expose:
      - 8888
  
  # Lavalink Server 1 - Production
  lavalink-1:
    image: ghcr.io/lavalink-devs/lavalink:latest
    container_name: lavalink-production-1
    restart: unless-stopped
    depends_on:
      - config-server
    environment:
      SPRING_CONFIG_IMPORT: configserver:http://config-server:8888
      SPRING_CLOUD_CONFIG_NAME: lavalink
      SPRING_CLOUD_CONFIG_PROFILE: production
      SPRING_CLOUD_CONFIG_USERNAME: admin
      SPRING_CLOUD_CONFIG_PASSWORD: youshallnotpass
    networks:
      - lavalink
    ports:
      - "2333:2333"
  
  # Lavalink Server 2 - Staging
  lavalink-2:
    image: ghcr.io/lavalink-devs/lavalink:latest
    container_name: lavalink-staging-1
    restart: unless-stopped
    depends_on:
      - config-server
    environment:
      SPRING_CONFIG_IMPORT: configserver:http://config-server:8888
      SPRING_CLOUD_CONFIG_NAME: lavalink
      SPRING_CLOUD_CONFIG_PROFILE: staging
      SPRING_CLOUD_CONFIG_USERNAME: admin
      SPRING_CLOUD_CONFIG_PASSWORD: youshallnotpass
    networks:
      - lavalink
    ports:
      - "2334:2333"

networks:
  lavalink:
    name: lavalink

Security Best Practices

Authentication

Always enable authentication on the Config Server
Use strong, unique passwords
Consider using OAuth2 for production deployments
Rotate credentials regularly

Network Security

Run Config Server on an internal network
Use TLS/SSL for all connections
Restrict access using firewall rules
Don’t expose the Config Server to the public internet

Git Repository

Use private repositories for production configs
Enable branch protection on main branches
Use Personal Access Tokens instead of passwords
Audit access to configuration repositories

Troubleshooting

Lavalink Can't Connect to Config Server

Check:

Config Server is running and accessible
Network connectivity between services
Correct hostname/IP and port
Authentication credentials are correct
Firewall rules allow connections

Config Server Returns 404

Verify:

Configuration files exist in the repository
File names match: application.yml or application-{profile}.yml
Files are in the correct directory (check search-paths)
Git repository has been cloned (check logs)
Branch/label specified exists

Configuration Not Updating

Check:

Refresh rate settings
Git repository has latest changes
Lavalink server needs restart for some changes
Cache settings on the Config Server
Profile name is correct

application.yml Reference

Complete configuration options

Environment Variables

Alternative configuration method

Config Server GitHub

Config Server source code and documentation

Example Configs

Example configuration repository

Get Started

Configuration

Clients & Plugins

Features

Centralized Management

Git Integration

Profile Support

Hot Reloading

Architecture

Lavalink Client Configuration

Using application.yml

Using Environment Variables

Config Server Setup

Docker Deployment

Config Server Configuration

Environment Variables for Config Server

Configuration Repository Structure

Profile Override Behavior

Example Config Repository

Complete Deployment Example

Security Best Practices

Troubleshooting

application.yml Reference

Environment Variables

Config Server GitHub

Example Configs

Build docs developers (and LLMs) love

Get Started

Configuration

Clients & Plugins

​Features

Centralized Management

Git Integration

Profile Support

Hot Reloading

​Architecture

​Lavalink Client Configuration

​Using application.yml

​Using Environment Variables

​Config Server Setup

​Docker Deployment

​Config Server Configuration

​Environment Variables for Config Server

​Configuration Repository Structure

​Profile Override Behavior

​Example Config Repository

​Complete Deployment Example

​Security Best Practices

​Troubleshooting

​Related Resources

application.yml Reference

Environment Variables

Config Server GitHub

Example Configs

Build docs developers (and LLMs) love

Features

Architecture

Lavalink Client Configuration

Using application.yml

Using Environment Variables

Config Server Setup

Docker Deployment

Config Server Configuration

Environment Variables for Config Server

Configuration Repository Structure

Profile Override Behavior

Example Config Repository

Complete Deployment Example

Security Best Practices

Troubleshooting

Related Resources