---
title: "Deploy JuggleIM"
description: "Self-hosted IM server with WebSocket, REST API and console"
category: "Other"
url: https://railway.com/deploy/deploy-juggleim-chat-server
---

# Deploy JuggleIM

Self-hosted IM server with WebSocket, REST API and console

**[Deploy JuggleIM on Railway](https://railway.com/template/deploy-juggleim-chat-server)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/deploy-juggleim-chat-server/manifest.json

- **Creator:** onepush
- **Category:** Other

## Template content

### juggleim https://api.iconify.design/mdi/chat-processing-outline.svg

- **Image:** ghcr.io/onepush-dev/juggleim:c01fa24
- **Health check:** /health
- **Public domain:** Yes

### mysql https://devicons.railway.app/mysql

- **Image:** mysql:8.0

## Documentation

# Deploy and Host self hosted JuggleIM (Other) on Railway

This template deploys JuggleIM, an Apache-2.0 self-hosted instant-messaging server, as a juggleim service behind one public HTTPS domain with a bundled MySQL database.

## About Hosting JuggleIM open-source software on Railway (self hosted JuggleIM template)

Running JuggleIM on Railway means the chat server, its admin console and its message store all live in your own Railway project, so you keep ownership of the users, groups, messages and app keys it holds.

This is independent community packaging of juggleim/im-server at commit c01fa24. It is not affiliated with or endorsed by JuggleIM.

## Why Deploy JuggleIM, the self-hosted instant-messaging server on Railway

Hosted per-MAU chat APIs charge more as your user base grows, and they hold your message data on their side.

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying JuggleIM on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

### Railway vs Other Hosting Providers and VPS for JuggleIM self hosting

Self-hosting JuggleIM means deciding where the server and bundled MySQL run.

| Provider | What You Get with Railway | What You Get with the Other Provider |
| --- | --- | --- |
| DigitalOcean | A template with juggleim and mysql, a public HTTPS domain for WSS, and health checks wired up. | A droplet you size and patch, with Docker, reverse proxy and TLS set up by hand. |
| AWS | The same template without building a VPC or certificates yourself. | Wide control over networking, with more to configure. |
| Hetzner | Managed deployment and domain routing with no server to administer. | Low-cost servers where you handle updates, backups and MySQL. |

Choose based on how much infrastructure you want to maintain.

## Common Use Cases for hosted JuggleIM

- **Multi-tenant chat backend:** Run one JuggleIM deployment that hosts several isolated apps, each with its own app key and secret, so separate products can share one server.
- **Real-time client connections:** Client SDKs for Web, iOS, Android and Flutter hold WebSocket long connections to the Railway domain for message delivery.
- **Signed server-side REST API:** Your backend calls the /apigateway endpoints with signed headers to register users, create groups and send messages.
- **Groups, chatrooms and history:** Build group chats, large chat rooms and message history on top of the bundled MySQL storage.

## Dependencies for JuggleIM Docker hosted on Railway

This template runs two services in one Railway project: a public juggleim service and a private bundled mysql service.

### Deployment Dependencies for Managed JuggleIM Service

The juggleim service is public on port 8080, has no volume, checks /health with a 300 second timeout, and uses the Always restart policy. The mysql service is private, uses image mysql:8.0, stores files under /var/lib/mysql, uses database jim_db, and restarts On Failure. Keep one replica of each service. Chat data lives in MySQL. Connection logs on the juggleim service are local and reset on redeploy.

### Implementation Details for JuggleIM

The image is ghcr.io/onepush-dev/juggleim:c01fa24, upstream juggleim/im-server built from commit c01fa241723bfb41fa882ac62134ec5f390a9908, binary unmodified, plus Caddy on port 8080 and railway/start.sh. Caddy path-routes /im, /imbot and /health to the WebSocket listener, /apigateway to the server API, /navigator to the navigator, and everything else to the admin console. On first boot the wrapper creates the schema, replaces the upstream default admin password, sets a per-deploy admin JWT secret, and registers the public domain as the wss connect address. Baked values are MYSQL_PORT=3306, MYSQL_DB_NAME=jim_db, MYSQL_USER=root and JUGGLEIM_ADMIN_USER=admin. The admin console is Chinese-first. Client SDKs connect over wss to the Railway domain.

- **JUGGLEIM_ADMIN_PASSWORD:** generated password for the console user admin.
- **JUGGLEIM_ADMIN_SECRET:** generated key that signs admin console sessions.
- **JUGGLEIM_PUBLIC_DOMAIN:** defaults to the Railway domain and is handed to SDKs as the wss connect address; change it if you add a custom domain.
- **MYSQL_HOST:** references the private hostname of the bundled mysql service.
- **MYSQL_PASSWORD:** references the password from the mysql service.
- **MYSQL_ROOT_PASSWORD:** generated MySQL root password on the mysql service.

## How does JuggleIM compare against other tools

### JuggleIM vs a hosted per-MAU chat API (Hosted Chat API Alternative)

- **Cost model:** Hosted chat APIs bill by monthly active users, so costs grow with your audience. JuggleIM is Apache-2.0 and free to self-host, and you pay only for the infrastructure.
- **Data location:** Hosted APIs keep message data on the vendor's servers. Here, chat data lives in the bundled MySQL service on your own Railway project.
- **Feature depth:** A managed vendor often offers polished dashboards and support plans. JuggleIM provides WebSocket connections, a signed server API, groups, chatrooms, history, push and an admin console, but you run the operations.

### JuggleIM vs a local Docker Compose install of JuggleIM (Local Docker Compose Alternative)

- **Reachability:** A local install listens on local ports such as 9001 to 9003 and 8090. This template runs behind one HTTPS domain, so client SDKs connect over wss to the Railway domain without extra proxy setup.
- **Persistence:** Local data sits on your workstation. On Railway the MySQL service has a volume at /var/lib/mysql, while the juggleim service has no volume and its connection logs reset on redeploy.
- **Admin access:** The Railway console is Chinese-first and you sign in as admin with the generated JUGGLEIM_ADMIN_PASSWORD, not the default password.

### JuggleIM with Docker vs Railway (Railway Hosting Alternative)

- **Control:** Running JuggleIM with Docker on your own host gives full control over networking and the Compose file. Railway handles builds, the public domain and restarts, with the health check on /health.
- **Scaling:** Keep one replica of each service, since the bundled MySQL holds the chat data.
- **Backups:** On Railway, back up the MySQL volume yourself and keep the generated secrets safe, since restores were not verified for this template.
- **Cost:** Railway bills on usage based on RAM, CPU and volume size.

## How to use JuggleIM on Railway?

1. Open the public domain from your deployment and sign in as `admin` with the password stored in `JUGGLEIM_ADMIN_PASSWORD` on the Variables tab. The default password `123456` is rejected.
2. Create an app in the admin console and note its app key and app secret. Keep the app secret on your backend only.
3. Your backend calls the Railway domain plus `/apigateway` with the documented signed headers to register users and get user tokens.
4. Client SDKs connect over wss to the Railway domain with the app key and user token.
5. If you add a custom domain, change `JUGGLEIM_PUBLIC_DOMAIN` so the navigator hands the new address to clients.
6. Keep one replica of each service. The health check path is `/health`, and chat data stays in the bundled MySQL service.

```
Health check: /health
Admin sign-in: admin / JUGGLEIM_ADMIN_PASSWORD
Client connect: wss://your-domain (via the navigator)
```

## How to self host JuggleIM on other VPS Services (JuggleIM self hosting guide)

Follow the upstream flow: run the documented Docker Compose or binary with MySQL and the published ports, as described in the upstream repository.

### Clone the Repository

Clone the upstream project at the commit this template packages.

```bash
git clone https://github.com/juggleim/im-server.git your-domain-im-server
cd your-domain-im-server
git checkout c01fa241723bfb41fa882ac62134ec5f390a9908
```

### Install Dependencies

Install Docker and Docker Compose on the VPS, or install Go and MySQL to run the binary directly.

### Configure Environment Variables

Set a strong admin password in place of the upstream default, and keep MySQL credentials private.

```bash
export MYSQL_HOST=your-mysql-host
export MYSQL_PASSWORD=your-mysql-password
export JUGGLEIM_ADMIN_PASSWORD=your-admin-password
```

### Start the JuggleIM Application

Start the stack from the cloned directory and check the published ports for the admin console, server API and WebSocket listener.

Railway handles the public domain, TLS, MySQL volume and restarts for you.

## Pricing and License of JuggleIM (JuggleIM pricing)

JuggleIM is released under the Apache-2.0 open-source license, so you can self-host it at no software cost.

## JuggleIM hosted vs self hosted comparison (Pricing, features, costs, and more)

This template packages the Apache-2.0 software at commit c01fa24.

### Monthly cost of self hosting JuggleIM on Railway

Railway bills by usage, so cost depends on RAM and CPU.

### System Requirements for Hosting JuggleIM on a VPS

A VPS needs enough memory and CPU for the juggleim service and MySQL, plus persistent disk for the database.

## Frequently Asked Questions (FAQs)

### How do I sign in to the admin console?

Open the public domain and sign in as admin with the JUGGLEIM_ADMIN_PASSWORD value from the Variables tab.

### How do client SDKs connect?

Client SDKs connect over wss to the Railway domain, and the navigator returns that same public domain as the connect address.

### Is the /health endpoint protected?

No, /health is open because the health check probe uses it on the public domain.

### Where is chat data stored?

Chat data lives in the bundled MySQL service, which keeps its data on the mysql volume at /var/lib/mysql.

### What should I back up?

Back up the MySQL volume, since it holds your users, groups, messages and apps.


## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — Self-hosted virtual tabletop for role-playing games (license required)
- [Double Commander in your browser](https://railway.com/deploy/double-commander-in-your-browser) — The Double Commander file manager in the cloud, from any device

Open this page in a browser: https://railway.com/deploy/deploy-juggleim-chat-server
