Installation

CoSky can be used in two ways: as a library dependency integrated into your Spring Cloud application, or as a standalone REST API server for centralized management with a web dashboard. This page covers all installation methods.

Installation Methods Comparison

Method	Pros	Cons	Best For
Spring Cloud Starter	Zero extra infrastructure; integrates directly into your app	No management UI; each app connects to Redis independently	Microservices that self-register and self-configure
Standalone JAR	Full dashboard; RBAC; audit logs	Requires a dedicated JVM process	Teams wanting a management console without containers
Docker	Portable; reproducible; easy to scale	Requires Docker runtime	Containerized environments, dev/test setups
Kubernetes	Cloud-native; health probes; auto-restart	Requires K8s cluster	Production cloud-native deployments

mermaid

%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#2d333b','primaryBorderColor':'#6d5dfc','primaryTextColor':'#e6edf3','lineColor':'#8b949e','secondaryColor':'#161b22','tertiaryColor':'#161b22'}}}%%
flowchart TD
    START["Choose Installation Method"] --> Q1{"Need central<br>management UI?"}
    Q1 -->|No| LIB["Spring Cloud Starter<br>(library dependency)"]
    Q1 -->|Yes| Q2{"Container<br>platform?"}
    Q2 -->|Docker only| DOCKER["Docker deployment"]
    Q2 -->|Kubernetes| K8S["Kubernetes deployment"]
    Q2 -->|Neither| JAR["Standalone JAR<br>deployment"]

    LIB --> REDIS1[("Redis")]
    DOCKER --> REDIS2[("Redis")]
    K8S --> REDIS3[("Redis")]
    JAR --> REDIS4[("Redis")]

    style START fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style Q1 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style Q2 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style LIB fill:#2d333b,stroke:#38a169,color:#e6edf3
    style DOCKER fill:#2d333b,stroke:#38a169,color:#e6edf3
    style K8S fill:#2d333b,stroke:#38a169,color:#e6edf3
    style JAR fill:#2d333b,stroke:#38a169,color:#e6edf3
    style REDIS1 fill:#2d333b,stroke:#dc382c,color:#e6edf3
    style REDIS2 fill:#2d333b,stroke:#dc382c,color:#e6edf3
    style REDIS3 fill:#2d333b,stroke:#dc382c,color:#e6edf3
    style REDIS4 fill:#2d333b,stroke:#dc382c,color:#e6edf3

As a Library Dependency

Add CoSky starters to your Spring Cloud application. These are published to Maven Central under me.ahoo.cosky.

Gradle (Kotlin DSL)

kotlin

val coskyVersion = "5.8.1"

dependencies {
    implementation(platform("me.ahoo.cosky:cosky-bom:${coskyVersion}"))
    implementation(platform("me.ahoo.cosky:cosky-dependencies:${coskyVersion}"))
    implementation("me.ahoo.cosky:cosky-spring-cloud-starter-config")
    implementation("me.ahoo.cosky:cosky-spring-cloud-starter-discovery")
    implementation("org.springframework.cloud:spring-cloud-starter-loadbalancer")
}

Maven

xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <artifactId>demo</artifactId>
    <properties>
        <cosky.version>5.8.1</cosky.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>me.ahoo.cosky</groupId>
                <artifactId>cosky-bom</artifactId>
                <version>${cosky.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <dependency>
                <groupId>me.ahoo.cosky</groupId>
                <artifactId>cosky-dependencies</artifactId>
                <version>${cosky.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>me.ahoo.cosky</groupId>
            <artifactId>cosky-spring-cloud-starter-config</artifactId>
        </dependency>
        <dependency>
            <groupId>me.ahoo.cosky</groupId>
            <artifactId>cosky-spring-cloud-starter-discovery</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-loadbalancer</artifactId>
        </dependency>
    </dependencies>
</project>

Source: gradle.properties:14, README.md:46-108

Available Artifacts

Artifact	Purpose	Module
`cosky-spring-cloud-starter-config`	Spring Cloud config loading and real-time refresh	cosky-spring-cloud-starter-config
`cosky-spring-cloud-starter-discovery`	Spring Cloud service registration and discovery	cosky-spring-cloud-starter-discovery
`cosky-bom`	Bill of Materials — manages CoSky module versions	cosky-bom
`cosky-dependencies`	Version catalog — manages Spring Boot / Spring Cloud / CosID / Simba / CoSec versions (required for the versionless `spring-cloud-starter-loadbalancer`)	cosky-dependencies

REST API Server Installation

The REST API server provides a management dashboard, REST endpoints, security (RBAC), and audit logging. It is optional -- your services work perfectly without it using just the library starters.

Option 1: Standalone JAR

GitHub releases do not publish prebuilt archives, so build the server distribution from source (JDK 17 required):

bash

# (Optional) Build the dashboard first so the web UI is bundled into the distribution
cd dashboard && pnpm install && pnpm build && cd ..

# Build the distribution archive
./gradlew :cosky-rest-api:distTar

# Extract (the archive name includes the version)
tar -xvf cosky-rest-api/build/distributions/cosky-rest-api-5.8.1.tar
cd cosky-rest-api-5.8.1

# Run with Redis connection
bin/cosky-rest-api --server.port=8080 --spring.data.redis.url=redis://localhost:6379

The distribution contains bin/ start scripts, lib/ dependencies, config/ configuration files, and ui/ with the dashboard static resources (served via spring.web.resources.static-locations: file:./ui/).

On first startup, CoSky initializes the super user and prints the generated password to the console:

log

---------------- ****** CoSky -  init super user:[cosky] password:[6TrmOux4Oj] ****** ----------------

To reinitialize the password, set enforce-init-super-user: true in your configuration.

Source: cosky-rest-api/build.gradle.kts:36-44, cosky-rest-api/src/dist/config/application.yaml:13, README.md:267

Option 2: Docker

Quick deployment with Docker:

bash

# Pull the image
docker pull ahoowang/cosky:latest

# Run as a container
docker run --name cosky -d -p 8080:8080 \
  -e SPRING_DATA_REDIS_URL=redis://your-redis-host:6379 \
  ahoowang/cosky:latest

Docker Compose

For local development with Redis:

yaml

version: "3.8"
services:
  redis:
    image: redis:7
    ports:
      - "6379:6379"
  cosky:
    image: ahoowang/cosky:latest
    ports:
      - "8080:8080"
    environment:
      - SPRING_DATA_REDIS_URL=redis://redis:6379
    depends_on:
      - redis

Source: README.md:159-163

Option 3: Kubernetes

Deploy CoSky in your Kubernetes cluster. The project provides deployment manifests for both standalone Redis and Redis Cluster configurations.

Standalone Redis

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: cosky
  labels:
    app: cosky
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cosky
  template:
    metadata:
      labels:
        app: cosky
      annotations:
        instrumentation.opentelemetry.io/inject-java: "true"
    spec:
      containers:
        - env:
            - name: SPRING_DATA_REDIS_HOST
              value: redis-uri:6379
            - name: SPRING_DATA_REDIS_PASSWORD
              value: redis-pwd
            - name: TZ
              value: Asia/Shanghai
          image: registry.cn-shanghai.aliyuncs.com/ahoo/cosky:5.8.1
          startupProbe:
            httpGet:
              port: http
              path: /actuator/health
          readinessProbe:
            httpGet:
              port: http
              path: /actuator/health/readiness
          livenessProbe:
            httpGet:
              port: http
              path: /actuator/health/liveness
          name: cosky
          ports:
            - name: http
              containerPort: 8080
              protocol: TCP
          resources:
            limits:
              cpu: "1"
              memory: 1280Mi
            requests:
              cpu: 250m
              memory: 1024Mi
          volumeMounts:
            - mountPath: /etc/localtime
              name: volume-localtime
      volumes:
        - hostPath:
            path: /etc/localtime
            type: ""
          name: volume-localtime

Note: The example above uses the current release 5.8.1. The in-repo manifest (k8s/deployment/cosky.yml) still pins the older 5.3.5 tag — prefer the current release, or ahoowang/cosky:latest from Docker Hub.

Source: k8s/deployment/cosky.yml

Redis Cluster

For production environments using Redis Cluster, reference secrets for node and password configuration:

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: cosky
  labels:
    app: cosky
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cosky
  template:
    metadata:
      labels:
        app: cosky
      annotations:
        instrumentation.opentelemetry.io/inject-java: "true"
    spec:
      containers:
        - env:
            - name: LANG
              value: C.utf8
            - name: SPRING_DATA_REDIS_CLUSTER_NODES
              valueFrom:
                secretKeyRef:
                  name: redis-secret
                  key: nodes
            - name: SPRING_DATA_REDIS_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: redis-secret
                  key: password
            - name: SPRING_DATA_REDIS_CLUSTER_MAX_REDIRECTS
              value: "3"
            - name: SPRING_DATA_REDIS_LETTUCE_CLUSTER_REFRESH_ADAPTIVE
              value: "true"
            - name: SPRING_DATA_REDIS_LETTUCE_CLUSTER_REFRESH_PERIOD
              value: 30s
            - name: TZ
              value: Asia/Shanghai
          image: registry.cn-shanghai.aliyuncs.com/ahoo/cosky:5.8.1
          startupProbe:
            httpGet:
              port: http
              path: /actuator/health
          readinessProbe:
            httpGet:
              port: http
              path: /actuator/health/readiness
          livenessProbe:
            httpGet:
              port: http
              path: /actuator/health/liveness
          name: cosky
          ports:
            - name: http
              containerPort: 8080
              protocol: TCP
          resources:
            limits:
              cpu: "1"
              memory: 1280Mi
            requests:
              cpu: 250m
              memory: 1024Mi
          volumeMounts:
            - mountPath: /etc/localtime
              name: volume-localtime
      volumes:
        - hostPath:
            path: /etc/localtime
            type: ""
          name: volume-localtime

Source: k8s/deployment/cosky-cluster.yml

Kubernetes Service

yaml

apiVersion: v1
kind: Service
metadata:
  name: cosky
  labels:
    app: cosky
spec:
  selector:
    app: cosky
  ports:
    - name: rest
      port: 80
      protocol: TCP
      targetPort: 8080

Source: k8s/deployment/cosky-service.yaml

Deployment Architecture

mermaid

%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#2d333b','primaryBorderColor':'#6d5dfc','primaryTextColor':'#e6edf3','lineColor':'#8b949e','secondaryColor':'#161b22','tertiaryColor':'#161b22'}}}%%
graph TB
    subgraph K8s["Kubernetes Cluster"]
        style K8s fill:#161b22,stroke:#30363d,color:#e6edf3
        SVC["cosky Service<br>(ClusterIP:80)"]
        DEP["cosky Deployment<br>(1 replica)"]
        SVC --> DEP
    end

    subgraph Apps["Microservices"]
        style Apps fill:#161b22,stroke:#30363d,color:#e6edf3
        APP1["App 1<br>(config + discovery starters)"]
        APP2["App 2<br>(config + discovery starters)"]
        APP3["App 3<br>(config + discovery starters)"]
    end

    subgraph RedisInfra["Redis Infrastructure"]
        style RedisInfra fill:#161b22,stroke:#30363d,color:#e6edf3
        REDIS[("Redis<br>Standalone or Cluster")]
    end

    APP1 --> REDIS
    APP2 --> REDIS
    APP3 --> REDIS
    DEP --> REDIS

    style SVC fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style DEP fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style APP1 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style APP2 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style APP3 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style REDIS fill:#2d333b,stroke:#dc382c,color:#e6edf3

Configuration Reference

Key configuration properties for CoSky:

Property	Default	Description	Source
`spring.data.redis.url`	(required)	Redis connection URL (standalone)	bootstrap.yaml
`spring.data.redis.cluster.nodes`	(required for cluster)	Redis cluster node addresses	cosky-cluster.yml:23
`spring.data.redis.password`	—	Redis password	cosky.yml:23
`spring.cloud.cosky.namespace`	`cosky-{default}`	Isolation namespace for services and configs	CoSkyProperties.kt:30
`spring.cloud.cosky.config.enabled`	`true`	Enable config loading from Redis	CoSkyConfigProperties.kt:26
`spring.cloud.cosky.config.config-id`	`${spring.application.name}.yaml`	Config file ID to load	CoSkyConfigAutoConfiguration.kt:48
`spring.cloud.cosky.config.file-extension`	`yaml`	Default file extension	CoSkyConfigProperties.kt:28
`spring.cloud.cosky.config.timeout`	`2s`	Timeout for config loading	CoSkyConfigProperties.kt:29
`spring.cloud.cosky.discovery.enabled`	`true`	Enable service discovery	CoSkyDiscoveryProperties.kt:26
`spring.cloud.cosky.discovery.timeout`	`2s`	Timeout for discovery operations	CoSkyDiscoveryProperties.kt:28
`spring.cloud.service-registry.auto-registration.enabled`	`true`	Auto-register service on startup	bootstrap.yaml:9
`cosky.security.enabled`	`true`	Enable security on REST API server	application.yaml:16
`cosky.security.enforce-init-super-user`	`false`	Reinitialize super user password	application.yaml:19

Instance Lifecycle Properties

When using the discovery starter, service instances have configurable TTL and heartbeat settings:

Property	Default	Description	Source
Instance TTL	`60s`	How long an instance lives before being considered expired	RegistryProperties.kt:26
Renew period	`10s`	How often the instance sends a heartbeat to renew its TTL	RenewProperties.kt:28
Renew initial delay	`1s`	Delay before the first heartbeat after registration	RenewProperties.kt:23

mermaid

%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#2d333b','primaryBorderColor':'#6d5dfc','primaryTextColor':'#e6edf3','lineColor':'#8b949e','secondaryColor':'#161b22','tertiaryColor':'#161b22'}}}%%
sequenceDiagram
    autonumber
    participant App as Application
    participant Registry as ServiceRegistry
    participant Renew as RenewInstanceService
    participant Redis as Redis

    App->>Registry: register(instance)
    Registry->>Redis: Lua script: register instance
    Redis-->>Registry: OK

    Note over Renew,Redis: Heartbeat loop starts after 1s initial delay

    loop Every 10 seconds
        Renew->>Redis: renew(instance) - extend TTL
        Redis-->>Renew: OK
    end

    Note over App,Redis: On graceful shutdown
    App->>Registry: deregister(instance)
    Registry->>Redis: remove instance data
    Redis-->>Registry: OK

    Note over Redis: If heartbeat stops, instance expires after 60s TTL

REST API Server Bootstrap Configuration

The REST API server uses the following bootstrap configuration:

yaml

spring:
  application:
    name: ${service.name:cosky-rest-api}
  cloud:
    cosky:
      namespace: ${cosky.namespace:cosky-{system}}
      config:
        config-id: ${spring.application.name}.yaml
    service-registry:
      auto-registration:
        enabled: ${cosky.auto-registry:true}

Source: cosky-rest-api/src/dist/config/bootstrap.yaml

Accessing the Dashboard

Once the REST API server is running, access the web-based management interface at:

http://localhost:8080

The dashboard provides:

Real-time service monitoring and management
Configuration management with version control and rollback
Namespace isolation and management
Role-based access control (RBAC)
Audit logging for compliance
Service topology visualization
Import/export functionality (including Nacos migration)

Source: README.md:238-246

References

build.gradle.kts -- root build configuration with JVM 17 toolchain
gradle.properties -- project version (5.8.1)
settings.gradle.kts -- all module definitions
k8s/deployment/cosky.yml -- Kubernetes deployment (standalone Redis)
k8s/deployment/cosky-cluster.yml -- Kubernetes deployment (Redis Cluster)
k8s/deployment/cosky-service.yaml -- Kubernetes Service manifest
cosky-rest-api/src/dist/config/bootstrap.yaml -- REST API server bootstrap config
cosky-rest-api/src/dist/config/application.yaml -- REST API server application config

Installation ​

Installation Methods Comparison ​

As a Library Dependency ​

Gradle (Kotlin DSL) ​

Maven ​

Available Artifacts ​

REST API Server Installation ​

Option 1: Standalone JAR ​

Option 2: Docker ​

Docker Compose ​

Option 3: Kubernetes ​

Standalone Redis ​

Redis Cluster ​

Kubernetes Service ​

Deployment Architecture ​

Configuration Reference ​

Instance Lifecycle Properties ​

REST API Server Bootstrap Configuration ​

Accessing the Dashboard ​

References ​

Installation

Installation Methods Comparison

As a Library Dependency

Gradle (Kotlin DSL)

Maven

Available Artifacts

REST API Server Installation

Option 1: Standalone JAR

Option 2: Docker

Docker Compose

Option 3: Kubernetes

Standalone Redis

Redis Cluster

Kubernetes Service

Deployment Architecture

Configuration Reference

Instance Lifecycle Properties

REST API Server Bootstrap Configuration

Accessing the Dashboard

References