Huly Platform - Railway Template

Overview

This template deploys a complete, self-hosted Huly platform on Railway. Huly is an open-source project management and collaboration tool, similar to Linear, Jira, or Notion.

What's Included:

• 🗄️ CockroachDB - Distributed SQL database
• 📨 Redpanda - Event streaming platform (Kafka-compatible)
• 📦 MinIO - S3-compatible object storage
• 🔍 Elasticsearch - Full-text search engine
• 🔐 Account Service - User authentication & management
• 📋 Workspace Service - Project & task management
• 🤝 Collaborator Service - Real-time collaboration
• 💾 Transactor Service - Data persistence layer
• 🎨 Front-end - Web interface
• 🔀 Caddy - Automatic reverse proxy with HTTPS

Deploy and Host

About Hosting

Huly requires multiple interconnected services: database layer, message broker, object storage, search engine, application services, and reverse proxy. Railway automatically handles networking between services, provides persistent storage volumes, and offers seamless SSL certificate provisioning. Private networking keeps internal services secure while exposing only necessary public endpoints through Caddy.

Why Deploy

Self-Hosted Control: Complete control over your data and customization options, eliminating recurring subscription fees. Own your infrastructure and modify it to meet exact needs.

Cost Efficiency: For 10+ users, self-hosting is more cost-effective than per-seat pricing. A $100-150/month Railway deployment serves 50 users vs $500-1000+/month for comparable SaaS.

Data Privacy & Compliance: Keep sensitive project data within your infrastructure. Essential for strict data residency requirements, HIPAA compliance, or confidential information that cannot be stored with third-party providers.

Customization Freedom: Open-source nature allows modifying workflows, adding custom features, integrating with internal tools, and adapting to specific processes without vendor limitations.

No Vendor Lock-in: Data remains portable and accessible. Migrate, backup, or export anytime without negotiating with SaaS providers or dealing with restrictive APIs.

Common Use Cases

Software Development Teams: Track sprints, manage backlogs, coordinate releases, and maintain technical documentation in one platform.

Product Management: Plan roadmaps, gather customer feedback, prioritize features, and coordinate cross-functional initiatives with visibility across engineering, design, and business teams.

Agency Project Management: Handle multiple client projects with separate workspaces. Track billable hours, manage deliverables, and maintain client communication history.

Startup Operations: Central hub for small teams needing issue tracking, wiki documentation, and project coordination without enterprise complexity or costs.

Remote Team Coordination: Real-time collaboration for distributed teams needing shared task management, asynchronous communication, and transparent project visibility.

Internal IT Service Management: Create help desk workflows, track infrastructure tasks, maintain runbooks, and manage internal service requests with customizable issue types.

Dependencies for

Deployment Dependencies

Infrastructure Services (Must start first):

• CockroachDB: Primary database storing all application data. All application services depend on this being healthy.
• Redpanda: Message broker enabling real-time communication between services. Required for live updates and collaborative features.
• MinIO: Object storage for file uploads, attachments, and media. Used by Workspace, Collaborator, and Transactor services.
• Elasticsearch: Powers search functionality. Platform can start without it, but search features will be unavailable.

Application Services (Depend on infrastructure):

• Account Service: Authentication, user management, and JWT token generation. Must run for any user to log in. Depends on: CockroachDB
• Transactor Service: Core data persistence layer managing all write operations. Critical for any data modifications. Depends on: CockroachDB, MinIO, Redpanda
• Collaborator Service: Real-time collaboration, presence indicators, and live document editing. Depends on: CockroachDB, MinIO, Redpanda, Transactor
• Workspace Service: Workspace creation, project management, and task operations. Depends on: CockroachDB, MinIO, Transactor

User-Facing Services:

• Front-end: Web interface communicating with all application services. Depends on: Account, Workspace, Collaborator, Transactor
• Caddy: Reverse proxy providing public HTTPS access and routing requests. All user traffic flows through Caddy.

Service Startup Order: CockroachDB/MinIO/Elasticsearch/Redpanda (parallel) → Account/Transactor (parallel) → Workspace/Collaborator (parallel) → Front-end → Caddy

Critical Variables: All application services share SERVER_SECRET from Account service for JWT validation. Services reference each other using Railway's internal networking (.railway.internal domains). Front-end requires correct public URLs matching Caddy's domain.

Quick Start

1. Click "Deploy on Railway" button above
2. Wait 5-10 minutes for all services to deploy
3. Click on Caddy service and generate a public domain
4. Access your Huly instance at the generated URL
5. Create your first admin account

Post-Deployment Setup

1. Generate Public Domain

Go to Caddy service → Settings → Networking → Generate Domain. Copy the domain (e.g., your-app.up.railway.app)

2. Update Front-end Variables

Template should auto-populate these, but verify: ACCOUNTS_URL → https://your-domain.up.railway.app/account, COLLABORATOR_URL → wss://your-domain.up.railway.app/collaborator, TRANSACTOR_URL → wss://your-domain.up.railway.app/transactor

3. First Login

Navigate to your public domain, click "Sign Up", fill in details to create first admin user, then start creating workspaces and inviting team members.

Configuration

Environment Variables

All services pre-configured with optimal defaults. Key variables to customize: MinIO - MINIO_ROOT_USER (Default: minioadmin), MINIO_ROOT_PASSWORD (Auto-generated). Account Service - SERVER_SECRET (Auto-generated, shared across all services for JWT token signing and encryption).

Custom Domain

1. Go to Caddy service → Settings → Networking
2. Add your custom domain
3. Configure DNS: Add CNAME record pointing to Railway's domain, wait for DNS propagation (5-60 minutes)
4. Caddy will automatically provision SSL certificates

Scaling

Go to service → Settings → Deploy → Adjust "Number of Replicas". Recommended: Keep databases (CockroachDB, Elasticsearch) at 1 replica. Scale application services as needed. Front-end scales horizontally without issues.

Resource Requirements

Minimum (1-10 users): ~8GB total RAM, ~$50-70/month Recommended (10-50 users): ~16GB total RAM, ~$100-150/month

Per-service: CockroachDB (~2GB RAM, ~$10-15/month), Elasticsearch (~2GB RAM, ~$15-20/month), Redpanda (~1GB RAM, ~$5-10/month), MinIO (~512MB RAM, ~$5/month), Application services 5x (~512MB each, ~$25-40/month total), Caddy (~128MB RAM, ~$5/month)

Troubleshooting

Services Won't Start

Check logs in order: CockroachDB → Redpanda/MinIO/Elasticsearch → Account/Workspace/Transactor/Collaborator → Front-end/Caddy

Common issues: Out of memory (Elasticsearch needs 1GB+ RAM), Connection refused (wait for infrastructure services to be fully healthy), SERVER_SECRET mismatch (verify all application services reference ${{account.SERVER_SECRET}})

Can't Access Web Interface

1. Check Caddy service logs for errors
2. Verify Caddy has a public domain generated
3. Check Front-end environment variables point to correct domain
4. Ensure all services show "Active" status in Railway

Database Connection Errors

Check CockroachDB is running and healthy. Verify DB_URL in all services: postgresql://[email protected]:26257/huly?sslmode=disable. Check service logs for specific connection errors.

Security Best Practices

1. Change Default Passwords: Update MINIO_ROOT_PASSWORD to a strong password
2. Use Custom Domain with SSL: Railway provides automatic SSL with custom domains
3. Regular Backups: Set up periodic exports of CockroachDB, enable MinIO bucket versioning
4. Monitor Resource Usage: Check Railway metrics regularly, set up cost alerts, monitor database size growth

Backup & Recovery

Database Backup

npm install -g @railway/cli
railway login
railway run cockroach dump huly --insecure > backup-$(date +%Y%m%d).sql

MinIO Backup

mc alias set myrailway https://your-domain.up.railway.app/files minioadmin YOUR_PASSWORD
mc mirror myrailway/huly ./local-backup/

Costs & Pricing

Railway pricing: Starter Plan $5/month + usage (~$0.000231/GB-hour of RAM, ~$0.01/GB storage/month)

Estimated monthly costs:

Includes all services, storage, and bandwidth

Support & Resources

• Huly Documentation: https://docs.huly.io
• Railway Documentation: https://docs.railway.app
• GitHub Issues: https://github.com/hcengineering/platform/issues

Contributing

Found an issue with this template? Please Post About it Here https://station.railway.com

License

This deployment template is MIT licensed. Huly platform is licensed under EPL-2.0.

Built with ❤️ for the Railway community