Installation

This guide is for running OneCamp on your own server, with a lifetime licence or a free one for up to 25 people. OneCamp Cloud subscribers do not install anything — the hosting is set up for you.

You need an Ubuntu or Debian server with Docker, a public IP, 4 GB of RAM and 40 GB of disk. (On another Linux, build from source.) With 8 GB or more, uploads are also scanned for viruses. A domain is optional: without one, the workspace answers at once on a free address.

1. Run the installer, on the server

Run this on the server, replacing the key with the one from your licence email:

/bin/bash -c "$(curl -fsSL https://backend.onemana.dev/onecamp/download/YOUR-LICENSE-KEY)"

It asks three things, and only the last is required:

1. Which edition: with AI features (AI teammates and agents), or without AI at all. Both come with your key; type the number or the name.
2. Your domain, for example acme.com, which your team opens as onecamp.acme.com. Press Enter to skip it, and the workspace starts on onecamp.<your-ip>.sslip.io, a free address that already points at this server, with a real certificate and no DNS records to create.
3. The email of the first admin.

Then it sets everything up: every credential is generated, the database is created, the web app is built and served from this server, and the result is checked. Allow 10 to 20 minutes on a first run. It ends by printing the address to open.

2. Or run the setup yourself

If you unpacked the release some other way, or built it from source, run the same setup from that directory:

make install EMAIL=you@example.com                      # free address, no DNS
make install EMAIL=you@example.com DOMAIN=example.com   # your own domain

With your own domain it prints the DNS records to create (A records for onecamp, onecamp-backend, onecamp-emqx, onecamp-minio, onecamp-collab, onecamp-livekit and onecamp-turn). Add them, then re-run if certificates were not yet issued. A password for the Traefik dashboard is generated and printed once; pass PASSWORD= to choose your own.

Moving from the free address to your domain later is two commands. Create the DNS records first, then:

make replace-domain DOMAIN=example.com
make build_restart_all

About the free address. sslip.io is a public service that resolves any name containing an IP address to that IP. Let's Encrypt shares one weekly certificate quota across everyone who uses it; if that quota is used up, the installer moves to nip.io, which works the same way, by itself. It is ideal for trying OneCamp and for small teams; for a workspace people depend on, use your own domain.

3. Check it

make verify

make verify inspects the running system: every container up, migrations applied, the backend connected to Postgres, Dgraph, Redis, MinIO, EMQX and OpenSearch, and your domain answering over HTTPS. It reports every problem it finds rather than stopping at the first, and is safe to re-run.

It also checks that the server's own storage key opens its bucket, so files can be uploaded; make storage-check runs that check on its own.

make doctor is the counterpart for configuration — it checks .env before you start, where verify checks the result after.

When something isn't right, make logs SERVICE=go-service shows a service's last 200 lines (web, traefik and the others work the same way; add LINES=1000 for more).

4. Open the web app

make install also builds the web app on this server, for your domain and your edition, and serves it at onecamp.<your domain>. There is nothing else to deploy.

The first build takes a few minutes, and make verify says when the web app answers. make update rebuilds it together with the server.

Installed before the server served the web app? Update, then run make web_up to serve the web app from this server, and point onecamp.example.com here.

Prefer to host the web app yourself on Vercel, Netlify or another server? Install with WEB=0, or run make web_down later, and deploy the frontend repository (MIT licensed). Clone the branch that matches your edition, because the default branch is the one without AI:

git clone -b ai   https://github.com/OneMana-Soft/OneCamp-fe   # with AI
git clone -b main https://github.com/OneMana-Soft/OneCamp-fe   # without AI
cd OneCamp-fe && pnpm install && pnpm configure --domain example.com

Then point onecamp.example.com at that deployment instead of this server.

5. Create the first admin

Open https://onecamp.example.com/admin-setup and create the account, using the same email you gave make install. The page accepts only that address, so the workspace cannot be claimed by whoever reaches the URL first, and it works once: after an admin exists it refuses. To change the address before you set up:

make update-admin-email EMAIL=you@example.com
make restart-api

Updating

To see whether there is anything to update, open the admin panel, System, Health and updates, and click Check for updates. It shows the release you run and the newest one on your edition. It asks only when you click, and sends nothing about your workspace. If it can't say which release you run, update once and it will.

To update, run the same command you installed with — the one from your licence email. It compares what you are running against the current release on your edition, offers the newer one, and after unpacking asks whether to apply it.

Applying it backs up the database first, migrates, rebuilds, restarts, and then runs the same checks make verify does. Any step failing stops the rest, so a migration never lands against an image that was not built.

If you decline, the files are staged and nothing has changed. Finish whenever you like:

make update

Your .env, your data and your uploads are untouched by an update. The backup it takes first is under ./data/backups — keep it until you are happy, then remove it.

Updating does not change your edition. To move to the other edition, choose it when the installer asks.

Changing the LiveKit key

Calls are signed with a LiveKit key that is made when you install. To change it, for example if it was shown somewhere it shouldn't have been, run:

make rotate-livekit-key

It keeps a copy of your .env first (readable only by your account), writes the new key, restarts the services that use it, and checks they are back. Calls in progress end; people can join again straight away. If the services don't come back, it puts the old key back and says how to try again. The key is never printed.

Installs and updates before 16 October 2026 printed the LiveKit key in a warning on the terminal. If that output was saved or shared (a provisioning log, a CI job, a support email), update, then run make rotate-livekit-key.

If you are locked out

Your admin password is set once and never stored anywhere we or you can read it back from, so it cannot be looked up or resent. A new one is the only way in.

Every command below runs on the server, needs nothing but shell access, and works whether or not email is switched on.

make reset-link EMAIL=you@example.com

Prints a one-time link that lets you choose a new password. Prefer this one: nobody has to read a password out loud, and the link expires.

make reset-password EMAIL=you@example.com

Sets a password directly and prints it. For when the reset page itself cannot be reached.

make clear-2fa EMAIL=you@example.com

Only when the authenticator and every recovery code are gone. Deliberately separate from a password reset.

make change-email OLD=old@example.com NEW=new@example.com

When the mailbox itself is gone, so no link could ever reach you.

Each command tells you if the account has two-factor turned on, because a new password alone will not sign you in then.

What you configure afterwards, in the admin panel

None of these need a config file.

• Google / GitHub sign-in — add your own OAuth client id and secret.
• Email — add a Resend API key. Do this first. Until you do, your workspace cannot send anything. Inviting someone still works: the invite dialog says no email will go out and shows a link you can share yourself. But "forgot password" fails silently, answering "check your email" either way, because that endpoint deliberately gives the same answer whether or not an account exists. make verify reports this as a TODO.
• AI — choose a provider and paste your key, or run models locally.

AI models

OneCamp does not ship a model. You choose where inference happens.

Use your own provider key. In the admin AI panel, pick openai, anthropic, or openai_compatible and paste your key. The last covers OpenRouter, Groq, Together, vLLM, LM Studio and any other /v1-compatible endpoint. Keys are encrypted with AI_CONFIG_KEK, and the server refuses to start if that key is unset — so a stored key is never protected by a value someone else could know.

Or run models on this server (edition with AI only):

make ollama_up        start the engine and pull models
make ollama_update    move to the pinned version
make ollama_down      stop it; models stay on disk

Local models need real memory — budget 8 GB or more beyond the rest of the stack. On a small server, a hosted provider key is the better choice.

Imports from your own network

An import that asks for a site address, like Jira's, connects only to public addresses: it carries the sign-in you give it, so it never sends that to a private or reserved address. If the address you type is on one, the import says so and goes no further.

If the site really is on your own network, the server's operator can allow it. Set this in .env, then run make restart-api:

IMPORT_PRIVATE_HOSTS=tools.corp.example,10.20.0.0/16

• It is optional, and empty by default.
• List exact host names, IP addresses or CIDR ranges, comma separated.
• Names are looked up when the server starts. A name that can't be found then is left out, with a warning in the log, until the next restart.
• Loopback and link-local addresses are never used, even when listed.
• An entry that isn't a host name, an address or a range stops the server from starting, and make logs SERVICE=go-service shows a message naming it.
• Every server process reads it when it starts. If you run separate workers (Scaling a self-hosted workspace), start them again the same way so they read it too.

Reaching the admin consoles

The EMQX dashboard, MinIO console and OpenSearch Dashboards are deliberately not published to the internet. Reach them over an SSH tunnel:

make console-tunnel

That prints the exact ssh -L command and the localhost URLs to open.

The MinIO console lets you browse the stored files; it no longer manages access keys. You don't need it to: on every start OneCamp makes the storage bucket and the server's own access key if they are missing, leaves them alone if they are there, and never changes or prints a secret. make storage-check says whether that key opens the bucket, and make logs SERVICE=minio-init says what the last start made.

Every address shows "404 page not found" after a Docker upgrade

Docker 29, which the installer sets up and which Ubuntu 24.04's updates now install, refuses the old way Traefik 3.0 asked it for the running services. Your workspace's proxy then knows no routes, and every address answers "404 page not found"; make logs SERVICE=traefik says "client version 1.24 is too old".

Updating fixes it: re-run the install command you installed with, then make update. The proxy is now Traefik 3.7.13, and your certificates are kept. To get the workspace answering straight away, run these two lines in your OneCamp directory first:

sed -i 's#image: "traefik:v3.0"#image: "traefik:v3.7.13"#' sample-compose.yml
docker compose --env-file .env --project-name onecamp -f sample-compose.yml up -d traefik

Don't downgrade Docker or lower its minimum API version to work around it.

Staying signed in through an update

The sessions that keep people signed in are kept on the server, in data/redis_data/data, so an update no longer signs everyone out. Updates before this one kept them only inside a container that each update replaced, so the first update that keeps them signs everyone out one last time.

If you downloaded before 22 August 2026

Re-run the installer. It always fetches the current release on whichever edition you choose, so there is no version to look up.

Archives published before that date contained firebase-cred.json, a service-account credential belonging to OneMana. It granted access to a OneMana Firebase project — not to your workspace, your server, or your data — and it has been rotated. Delete any older archive you kept.

Those releases also baked a copy of your .env into the container image, so your own database password and encryption keys were sitting inside it. That is fixed in the same update.