How to Use Huly: The Beginner's Guide (Cloud vs Self-Host, First Workspace, First Tracker Project, and the GitHub-App Lesson)
CodexFuse Team · 2026-10-31T23:06:37.038Z · 18 min read
Learn how to use Huly: pick cloud vs self-host, create your first workspace, run your first Tracker project, and wire up the GitHub sync.
How to Use Huly: The Beginner's Guide (Cloud vs Self-Host, First Workspace, First Tracker Project, and the GitHub-App Lesson)
Learning how to use Huly is the step that turns "we pay for five separate tools" into "the whole team works in one place." Huly is an open-source, all-in-one collaboration platform that puts a Linear-style issue tracker, a Notion-style document editor, a Slack-style chat, team calendars, contacts, email, and a virtual office with voice and video calls into a single workspace. There are two ways to run it: Huly Cloud, a hosted service with a free tier, or a self-hosted install on your own server, where the software itself costs nothing and you own all your data. This huly tutorial — and the huly for beginners guide the field is missing — walks the complete beginner arc: the cloud-versus-self-host decision, the actual server install, your first workspace, your first Tracker project, your first issue, the team invites, the GitHub-App lesson that ties your code to your plan, and a fast tour of everything else in the box. Everything below was verified against the official huly-selfhost repository, the Huly docs, and the platform's live release data — because self-hosting Huly is a real infrastructure commitment, and this guide treats it like one.
You will do this in order: decide between Cloud and self-host with a clear cost picture, install the self-hosted stack with Docker (the Docker beginner guide covers the container basics if you need them), create your first workspace, run your first Tracker project, invite your team, wire the GitHub sync, and take the chat/docs/calendar tour. By the end you will know exactly what Huly replaces, what it costs to run, and whether it belongs at the center of your team's workflow.
What is Huly, exactly?
As open source project management software, Huly is an open-source, all-in-one team collaboration platform — a single workspace that replaces your issue tracker, your team chat, your wiki, your calendar, your contacts, and your meeting tool. The platform's source code is published by hcengineering under the Eclipse Public License 2.0, a weak-copyleft open-source license, and the project is actively developed (the public repository carries roughly 28,000 GitHub stars, dates back to August 2021, and was pushed to within the last day as of this writing). Where tools like Jira or Linear sell you per-seat subscriptions for one job, Huly sells you a whole office: Tracker (project management), Chat (messaging), Documents (real-time collaborative docs), Calendar, Contacts, Mail, Inbox, HR, and a virtual office with audio/video calls — all in one app you can host yourself or rent as cloud.
Should you use Huly Cloud or self-host Huly?
Pick Huly Cloud if you want the team working today with zero server responsibility; self-host if data control or per-seat economics matter more to you than convenience. Here is the decision the Huly team itself frames in their own writing: among roughly 30,000 cloud workspaces, only 2–3 have ever grown past the free tier's limits — most teams simply never outgrow it (huly.io, "Beyond the Cloud," 2026).
| Question to ask yourself | Cloud wins when… | Self-host wins when… |
|---|---|---|
| Budget shape | You prefer a predictable per-workspace bill (free to start) over a VPS bill | Your team is large and per-seat SaaS fees would dwarf a VPS |
| Data control | Fine with your workspace living on Huly's infrastructure | Contracts, clients, or policy require data on your own servers |
| Server skills | Nobody wants to be on-call for Docker updates and backups | You (or someone you trust) can run Docker, nginx, and backups |
| Customization | The standard app is enough | You want to extend, fork, or deeply integrate the EPL-2.0 code |
| Voice/video | Calls just work (Huly runs the Cloudflare-backed services) | You are willing to wire LiveKit yourself for the Love voice/video service |
The honest version of the self-host case is this: the software license is free, but the server, the storage, the bandwidth, and your time are not. A serious self-hosted Huly needs a server of at least 2 vCPUs and 8 GB of RAM (4 vCPUs and 16 GB recommended), plus backups, plus someone to read the MIGRATION.md file before every upgrade. For a solo dev testing the waters, the Cloud free tier wins. For a 30-person team paying per-seat for Jira + Slack + Notion, self-hosting can pay for itself in a month.
How much does Huly cost?
Huly Cloud charges by workspace resources, not by headcount — every plan includes unlimited users and unlimited Huly objects (issues, messages, wiki pages); only file attachments count against storage, and only voice/video calls count against traffic (therundown.ai, 2026). Self-hosting has no Huly subscription fee at all.
| Plan | Price | Storage | Audio/video traffic |
|---|---|---|---|
| Common | $0/month | 10 GB | 10 GB |
| Rare | $19.99/month | 100 GB | 100 GB |
| Epic | $99.99/month | 1 TB | 500 GB |
| Legendary | $399.99/month | 10 TB | 2 TB |
Two pricing facts worth knowing before you commit: the AI and MetaBrain features are still listed as "to be determined" on every tier, so budget them at OpenAI rates or less when they land; and a custom enterprise plan exists on request. If you are comparing the free tier against per-seat tools, do the math for your actual team: a 20-person team on Jira Standard alone costs more per month than Huly's entire $19.99 Rare tier.
How do you install Huly on your own server?
Installing Huly means cloning the official huly-selfhost repository, running its setup script, and letting Docker Compose start the whole platform. This is the huly self host section: read it whole before you type anything, because Huly is resource-heavy, and the guide's own requirements say servers below 2 vCPUs and 8 GB of RAM may stop responding or fail entirely. For a production team, what is VPS hosting covers choosing the server itself.
- Check your server. Ubuntu 24.04 (or any modern Linux), 2 vCPUs and 8 GB RAM minimum, 4 vCPUs and 16 GB recommended, with Docker and Docker Compose installed. A cheap VPS at the minimum will run a small team; below it, do not bother.
- Try it locally first. On any machine with Docker, run:
git clone https://github.com/hcengineering/huly-selfhost.git,cd huly-selfhost,./setup.sh --quick. This useslocalhost:8087, skips every configuration prompt, and starts all services automatically — you will be looking at a Huly login screen in under 90 seconds, once services finish initializing (about 60 seconds of container startup). Quick mode is for local testing only, never production. - Do the real setup on the server. Run
./setup.sh(no--quick). The script is interactive: it asks for your host address (your domain, e.g.huly.yourcompany.com), whether to use HTTPS, and where to store persistent data. It generateshuly_v7.confwith your chosen values plus secrets, and writes yournginx.conf. You can accept the default Docker named volumes or point each data volume at a host path like/var/huly/db— if you do, set ownership (chown -R 1000:1000for most services; Redpanda's data wants user 101). - Wire nginx. Symlink the generated config into your system nginx:
sudo ln -s $(pwd)/nginx.conf /etc/nginx/sites-enabled/huly.conf, thensudo nginx -s reload. If you ever change the host address, HTTPS setting, port, or bind address, re-run./nginx.shto regenerate the config (it preserves your custom SSL additions). - Start the stack.
sudo docker compose up -d. Watchdocker compose psuntil the services are up, then open your domain in a browser. - Sign up and create the workspace. Fill in name, email, and a secure password on the sign-up screen, then create your first workspace (e.g. "Acme Team"). Workspaces are isolated; one server can host several.
- Lock the front door. Set
DISABLE_SIGNUP=truein theaccountandfrontservices of the compose file (or your.env), then recreate the stack. After that, new accounts can only join through an invite link to a specific workspace — do this before you share the URL anywhere. Create your own admin account first, or use the bundled development tool to make the first one. - Add mail. Email confirmation and notifications come from the
mailservice: point it at your SMTP server (host, port — 587 is the sane choice — credentials) or at Amazon SES. SMTP and SES are mutually exclusive, and on v0.6.470+ the variable isMAIL_URLon theaccountandtransactorservices. If sign-ups fail while the UI loads fine,docker compose logs -f accountis where you look first. - Turn on push notifications. Install
web-pushvia npm, generate a VAPID key pair, addPUSH_PUBLIC_KEYto thefrontservice and both keys to thenotificationservice (v0.7.x and later; the legacysesservice is gone), pointtransactorat it withWEB_PUSH_URL=http://notification:8091, and restart. - Back up before you need to. The repo ships
backup-create.shandbackup-restore.sh; schedule the backup script and test a restore to another machine once. Also bookmarkMIGRATION.md: before every version upgrade, read the section for your target version — 0.6.x to 0.7.x upgrades have dedicated migration steps that a plaindocker compose pullwill not do.
What are the real resource costs of self-hosting Huly?
Huly's own README warns, in plain language, that the provided CockroachDB and Redpanda deployments "might not be production-ready" and should be inspected before you trust them with real data. That warning is the whole cost lesson in one line. The default stack runs roughly 30 containers — the application services (front, account, workspace, transactor, collaborator, fulltext, stats, kvs, rekoni) plus the data layer (CockroachDB, Elasticsearch, MinIO, Redpanda) plus nginx — and the optional services are deliberately off until you add them: the AI bot (OpenAI key + MongoDB), voice/video via LiveKit (the Love service), web push, print, export, Telegram notifications, Google Calendar sync, GitHub sync, and OIDC/GitHub-OAuth login. The default compose is effectively the minimal profile; each extra service is an opt-in container you uncomment or add yourself.
Three things to know about that stack. First, HulyPulse — the service behind push notifications, typing indicators, and "who is viewing this" presence — supports an in-memory backend since v0.7.375, so small single-node deployments do not need Redis at all; Redis only becomes the backend for multi-node or high-availability setups. Second, CockroachDB is where all workspace data lives, which is why the CockroachDB beginner guide pairs well with this one. Third, the Kubernetes path exists (kube/ and a Helm chart in the repo), but the Docker Compose path is the documented, supported beginner route — start there.
How do you create your first workspace and invite your team?
After sign-up you land in workspace creation: give the workspace a name, and it becomes your team's isolated hub with its own Tracker, Chat, Documents, and settings. Admins can create multiple workspaces — handy for agencies keeping clients separate. The first account you create is effectively the admin, so make it a real address you control, then lock public sign-up (step 7 above) before inviting anyone.
Inviting is in the workspace Settings panel: invite teammates by email or by invite link, and assign roles — Admin, Member, or HR Manager — so people only see the modules they should. The settings panel also controls workspace branding and per-module access. One admin habit that pays off early: decide your module policy on day one (who gets Chat channels created, who can create Tracker projects), because an everything-app with no norms becomes a junk drawer fast.
How do you run your first Tracker project? (the huly tracker tour)
The Tracker is Huly's project management module — the Linear-style Kanban board where your team's actual work lives. Creating a project takes one dialog: give it a title (human-readable, e.g. "Mobile App"), a short unique identifier (e.g. TSK — every issue in the project becomes TSK-1, TSK-2, …), and default assignees and owners so new issues land on the right people automatically. Then you get the Kanban board: columns for the issue states, cards you can drag, and an interface that stays fast because the whole platform is built for keyboard-driven speed.
Creating an issue is one click: a modal opens where you add the title and description, then set priority, labels, and milestones. Milestones group issues into releases or sprints; labels are your cross-cutting taxonomy (bug, feature, docs). Use priorities honestly — if everything is "urgent," nothing is. From any document, you can @-mention a specific issue to link the spec directly to the work that implements it, so the context written in Documents never gets separated from the cards in Tracker.
How does the Huly GitHub integration work? (the GitHub-App lesson)
Huly's GitHub integration is a proper GitHub App that syncs issues, pull requests, comments, and reviews bi-directionally between your repositories and your Tracker projects. This is the feature that makes Huly a dev-team tool rather than a generic project manager, and it is the one most beginners set up wrong — because there are two different "GitHub integrations," and you want both for different reasons.
Lesson one: GitHub OAuth is just for login. In the self-host README's "Configure GitHub OAuth" section, you create a GitHub OAuth app, set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET on the account service, and users get a "Sign in with GitHub" button. That is authentication only — it does not sync anything.
Lesson two: the GitHub App is the sync engine. The "GitHub Service" section is the real integration: register a GitHub App (App ID, client ID/secret, a downloaded private key, a webhook secret), grant it the listed permissions (Issues, Pull requests, Contents, Commit statuses, Discussions, Projects, Pages, Webhooks — read/write; Metadata read-only), subscribe it to issue and PR events, and add the github container to your compose file with the webhook URL pointed at https://your-host/_github/api/webhook. Then, in a workspace, connect a Huly project to a GitHub repository: new GitHub issues appear as Huly tasks, new Huly issues are pushed back to GitHub, and inside a task's activity feed you can reference a PR number to tie the card to the code. On Huly Cloud the flow is the same shape but point-and-click: workspace Settings → Integrations → GitHub → Connect → authorize → map projects to repos (Better Stack, 2026).
The beginner mistake is connecting the repo and expecting magic before the webhook is verified — if issues only flow one way, the webhook secret or callback URL is wrong. And remember the self-host caveat from the docs: integrations like GitHub may need you to install the separate app yourself, and some Cloud-only bits (the proprietary Cloudflare pieces) are intentionally not in the self-host packages.
What else is inside the workspace? (the full app tour)
Huly is an everything-app, so the Tracker is only the start. Here is the rest of the box, each with the beginner move:
- Chat — Slack-style channels, direct messages, and threads. The power move: any message can be converted directly into a Tracker task with one click, so decisions made in chat stop evaporating into the scroll. If your wiki needs are simple, the Outline beginner guide covers a dedicated team-wiki alternative; Huly's Documents module is the built-in version.
- Documents — a Notion-like real-time collaborative editor with first-class code blocks (pick TypeScript, Python, Bash — real syntax highlighting, not grey boxes) and
@-links to Tracker issues. Write specs, design docs, and onboarding guides here. - Calendar — team calendars, plus a Google Calendar sync service you can enable (OAuth credentials on Google's side, the
calendarcontainer on yours). - Contacts — a CRM-lite for people and companies, with an HR module for roles like HR Manager.
- Mail — Gmail integration lets users connect their Gmail accounts and work email inside the platform (see the repo's Gmail configuration guide).
- Inbox — a unified notification center so you stop hunting across modules for what changed.
- Virtual office — the Love service adds audio/video calls on top of LiveKit, with channels for knock-and-join meetings and typing/presence powered by HulyPulse.
- AI — an optional AI bot (OpenAI-compatible;
gpt-4o-miniby default) for chat, message translation, and live translation of office calls.
Huly vs Plane: which one should you pick?
Plane is the other open-source, self-hostable project manager people compare against Huly, so here is the honest split: choose Huly when you want the whole office in one app — tracker plus chat plus docs plus calendar plus calls, all unified, with the GitHub sync built in. Choose Plane when you want a focused, best-in-class issue tracker and are happy to keep Slack, Notion, and your calendar as separate tools. Huly is the heavier bet (dozens of containers, 8 GB RAM minimum, real ops responsibility); Plane is the lighter, simpler self-host. If your team currently lives across four paid tools and hates the context-switching, Huly's everything-app pitch is the point. If your team just needs great issue tracking and nothing else, Huly's extra modules are weight you will never lift.
How is Huly different from Jira, Linear, Trello, and Asana?
The difference is scope and pricing shape, not just features. Jira, Linear, Trello, and Asana are each one tool (a tracker) sold per seat; Huly is the tracker plus the chat plus the docs plus the calls, with unlimited users on every Cloud plan and zero license cost self-hosted. Against Jira specifically — the enterprise default — Huly trades Jira's deep workflow customization and giant app marketplace for speed, simplicity, and one bill instead of five. Our Jira beginner guide covers the SaaS incumbent if you want to compare directly. The teams Huly fits best are product/engineering teams of roughly 5–50 people who are tired of paying per seat across four tools and are comfortable owning one server.
What are the 7 mistakes Huly beginners make?
| Mistake | What happens | Do this instead |
|---|---|---|
| Self-hosting on 4 GB of RAM | Services stop responding under load; you blame Huly | Minimum 2 vCPU / 8 GB; recommended 4 vCPU / 16 GB |
| Treating the bundled CockroachDB/Redpanda as production | Data loss risk on real workloads | Read the README warning and inspect the configs; plan managed DBs for production |
| Leaving public sign-up open | Strangers register on your workspace | Set DISABLE_SIGNUP=true before sharing the URL |
| Confusing GitHub OAuth with the GitHub App | Login works, nothing syncs | OAuth = login button; the GitHub App + webhook = two-way sync |
| Skipping MIGRATION.md on upgrade | Broken upgrades, especially 0.6.x → 0.7.x | Read the target version's section before docker compose pull |
| No backups tested | You discover the restore script is broken when you need it | Schedule backup-create.sh; test a restore once |
| One identifier scheme per person | Issue keys become chaos across projects | Decide the identifier convention (e.g. WEB, API, MOB) on day one |
Sources
- Huly self-hosted README — hcengineering/huly-selfhost (raw.githubusercontent.com), crawled 2026-10-31: system requirements, setup flow (
setup.sh,nginx.sh,huly_v7.conf), CockroachDB/Redpanda production warning, mail/SES, web push, GitHub OAuth vs GitHub Service, OIDC, disable sign-up, HulyPulse in-memory backend - Huly platform LICENSE — hcengineering/platform (raw.githubusercontent.com), crawled 2026-10-31: Eclipse Public License v2.0
- GitHub API, hcengineering/platform — latest release v0.7.426 (published 2026-07-05); ~28,031 stars; repo created 2021-08-02; pushed 2026-10-31
- Huly: Open-Source Platform to Replace Notion, Slack, and Linear — Better Stack Community (betterstack.com), crawled 2026-10-31: <90-second quick start, Tracker project dialog (title, identifier, assignees/owners), instant issue modal, bi-directional GitHub sync flow, Documents
@-mentions, message-to-task conversion, 8 GB resource lesson - Huly pricing and free plan — therundown.ai/tools/huly, crawled 2026-10-31: Common $0 (unlimited users, unlimited objects, 10 GB storage, 10 GB audio/video), Rare $19.99, Epic $99.99, Legendary $399.99, AI/MetaBrain TBD
- Huly Cloud pricing details — devtune.ai/verticals/issue-tracking-and-project-management/huly, crawled 2026-11-01: tier-by-tier resource allowances
- Beyond the Cloud — huly.io/blog/beyond-the-cloud, crawled 2026-10-31: ~30,000 cloud workspaces; 2–3 exceeding the free tier
- Self-hosting Huly — docs.huly.io/getting-started/self-host, crawled 2026-10-31: self-host docs pointer; Cloud-only Cloudflare bits excluded from self-host packages
- Installation guide for Huly — elest.io/open-source/huly/resources/installation-guide, crawled 2026-10-31: managed-install arc (Elestio)
- Huly: Free Open Source Everything App for Teams — blog.elest.io, crawled 2026-10-31: workspace/module overview (workspace, Tracker, chat, contacts, HR)
Frequently Asked Questions
Is Huly really free?
The software is free and open source (EPL-2.0), and Huly Cloud has a genuinely free Common tier: $0/month with unlimited users, unlimited issues/messages/wiki pages, 10 GB of storage, and 10 GB of audio/video traffic. Self-hosting has no Huly license fee, but you pay for the server (at least 2 vCPUs / 8 GB RAM), storage, bandwidth, and your own administration time.
Can Huly replace Jira and Slack?
That is the entire pitch: the Tracker module replaces Jira or Linear, Chat replaces Slack, Documents replaces Notion, and the virtual office replaces your meeting tool. What it does not replace is Jira's giant app marketplace or Slack's third-party integration catalog — teams deeply embedded in those ecosystems will feel the gap.
How hard is it to self-host Huly?
The install itself is easy — clone, ./setup.sh --quick, and you are logged in within about 90 seconds on localhost. Running it for a team is the hard part: a real server with 8+ GB RAM, backups you have tested, upgrades read from MIGRATION.md, and the README's own warning that the bundled CockroachDB and Redpanda configs are not production-ready. Community support only.
Does Huly sync with GitHub?
Yes, bi-directionally — but it needs the GitHub App, not just the GitHub OAuth login. Register a GitHub App, grant the documented permissions, add the github container with your webhook URL, then map Huly projects to repositories in the workspace integrations. GitHub issues become Huly tasks and Huly issues are pushed back; PR numbers referenced in a task's activity feed link the card to the code.
Should I pick Huly or Plane?
Pick Huly if you want the whole office — tracker, chat, docs, calendar, calls — in one self-hosted app with a GitHub sync, and you can spare the server and ops attention. Pick Plane if you want a lighter, focused open-source issue tracker and are happy keeping chat and docs as separate tools.
