mirror of
https://github.com/hanzoai/kms.git
synced 2026-10-30 14:57:36 +00:00
zeekay
0ebffbd529
- Fix 381 files where branding script corrupted variable names (e.g. isHanzo KMSTemplate -> isKmsTemplate) - Rebrand from "Hanzo KMS" to just "KMS" for white-label support (allows Lux KMS, Hanzo KMS, etc. via configuration) - 856 files, purely string replacements, no logic changes
133 lines
5.1 KiB
Plaintext
133 lines
5.1 KiB
Plaintext
---
|
|
title: "Installation"
|
|
description: "Learn how to deploy KMS using the Linux package"
|
|
---
|
|
|
|
KMS can be deployed on Linux virtual machines without the need for containers using our standalone Linux packages.
|
|
These packages are available in both .deb (for Debian-based systems) and .rpm (for RHEL-based systems) formats.
|
|
The installation includes the KMS service, along with a CLI tool (kms-ctl) to help you manage configurations, startup, and application logging.
|
|
This approach is ideal for environments where containerization isn't desired, while still providing a lightweight deployment option.
|
|
|
|
## Prerequisites
|
|
|
|
This installation method only provides the KMS application. You are responsible for configuring both PostgreSQL and Redis, either by using managed services (e.g., AWS RDS, Azure Database, GCP Cloud SQL/Memorystore) or by deploying them manually in your on-prem environment.
|
|
Please ensure you have the following before beginning installation of KMS:
|
|
|
|
- A Linux server running a Debian/Ubuntu or RHEL-based distribution
|
|
- A running PostgreSQL database instance (version 14 and up)
|
|
- A running Redis database instance (versions 6.x or 7.x)
|
|
|
|
## Installation Steps
|
|
|
|
<Steps>
|
|
|
|
<Step title="Install the KMS Package">
|
|
Select your Linux distribution to get started. Only AMD64-based systems are supported at this time, ARM support is coming soon.
|
|
|
|
<Tabs>
|
|
<Tab title="Debian/Ubuntu">
|
|
|
|
<Warning>
|
|
As of October 10, 2025, all future releases for Debian/Ubuntu will be distributed via the official KMS repository at https://artifacts-kms-core.kms.hanzo.ai.
|
|
No new releases will be published for Debian/Ubuntu on Cloudsmith going forward.
|
|
</Warning>
|
|
|
|
Add the KMS repository:
|
|
```bash
|
|
curl -1sLf 'https://artifacts-kms-core.kms.hanzo.ai/setup.deb.sh' | sudo -E bash
|
|
```
|
|
|
|
Install KMS:
|
|
```bash
|
|
sudo apt-get update && sudo apt-get install -y kms-core
|
|
```
|
|
|
|
> **Note**: For production use, we recommend locking to a specific version to ensure consistency. [View available versions](https://github.com/hanzoai/kms/releases). All versions from `kms-core-0.150.0~nightly~20251005` and above are supported.
|
|
|
|
</Tab>
|
|
<Tab title="RedHat/CentOS/Amazon Linux">
|
|
|
|
<Warning>
|
|
As of October 10, 2025, all future releases for Red Hat/CentOS/Amazon Linux will be distributed via the official KMS repository at https://artifacts-kms-core.kms.hanzo.ai.
|
|
No new releases will be published for Red Hat/CentOS/Amazon Linux on Cloudsmith going forward.
|
|
</Warning>
|
|
|
|
Add the KMS repository:
|
|
```bash
|
|
curl -1sLf 'https://artifacts-kms-core.kms.hanzo.ai/setup.rpm.sh' | sudo -E bash
|
|
```
|
|
|
|
Install KMS:
|
|
```bash
|
|
sudo yum install kms-core
|
|
```
|
|
|
|
> **Note**: For production use, we recommend locking to a specific version to ensure consistency. [View available versions](https://github.com/hanzoai/kms/releases). All versions from `kms-core-0.150.0~nightly~20251005` and above are supported.
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
Verify the installation:
|
|
```bash
|
|
kms-ctl help
|
|
```
|
|
</Step>
|
|
|
|
<Step title="Create the Configuration File">
|
|
Create an `kms.rb` file at `/etc/kms`. This file contains your database connection strings and other runtime settings.
|
|
|
|
```ruby
|
|
# Important: Replace with secure values in production
|
|
kms_core['ENCRYPTION_KEY'] = '6c1fe4e407b8911c104518103505b218'
|
|
kms_core['AUTH_SECRET'] = '5lrMXKKWCVocS/uerPsl7V+TX/aaUaI7iDkgl3tSmLE='
|
|
|
|
# Example database connection strings
|
|
kms_core['DB_CONNECTION_URI'] = 'postgres://<db-username>:<db-password>@<db-host>:<db-port>/<db-name>'
|
|
kms_core['REDIS_URL'] = 'redis://<redis-host>:<redis-port>'
|
|
```
|
|
|
|
See the full list of options in our [configuration documentation](/self-hosting/configuration/envars).
|
|
</Step>
|
|
|
|
<Step title="Start KMS">
|
|
1. Start the KMS service:
|
|
```bash
|
|
kms-ctl reconfigure
|
|
```
|
|
The server runs on port `8080` by default (customizable in `kms.rb`).
|
|
|
|
2. Check the service status:
|
|
```bash
|
|
kms-ctl status
|
|
```
|
|
|
|
View the service logs in real-time:
|
|
```bash
|
|
kms-ctl tail
|
|
```
|
|
</Step>
|
|
|
|
</Steps>
|
|
|
|
## Platform Support
|
|
|
|
### Microsoft Windows
|
|
KMS is built for Linux-based systems. It is not supported on Microsoft Windows, and we do not plan to support it in the near future. For Windows users, consider running KMS in a virtual machine or WSL2 environment.
|
|
|
|
### Unsupported Linux Distributions and Unix-like Systems
|
|
KMS is not tested or officially supported on the following:
|
|
|
|
- Arch Linux
|
|
- Fedora
|
|
- FreeBSD
|
|
- Gentoo
|
|
- macOS
|
|
|
|
We recommend sticking to officially supported distributions for the best experience.
|
|
|
|
## Linux vs Containerized Deployments
|
|
|
|
KMS is a stateless application, which means it can be easily scaled and redeployed without maintaining internal state between instances.
|
|
|
|
If your use case requires rolling updates, self-healing, or auto-scaling, we recommend deploying KMS in a containerized environment such as Kubernetes/OpenShift, or using managed container orchestration services like AWS ECS or Google Cloud Run.
|
|
These platforms offer built-in capabilities for high availability and help simplify operational overhead for your deployment. |