Umiji

Something's not working? Start here.

The problems people run into most, with what causes each one and how to fix it. Commands run on the server, as root, unless it says otherwise.

Installing

The installer stopped with an error #

Read the box it shows: What happened has the last lines of the failed step, and How to fix it says what to do. The whole log is in /var/log/umiji-install.log.

Fix it, then type umiji, or run the installer again. It keeps what it has already done.

It says it needs root #

Become root, then run the same command again:

sudo -i

It can't reach GitHub or ghcr.io #

The install files come from GitHub and the images from ghcr.io. Check that the server can open them:

curl -I https://ghcr.io

No answer usually means the server's DNS or firewall is blocking it. If its network blocks GitHub, the DEPLOY.md troubleshooting shows how to bring the images over from another machine.

Ports 80 and 443 are in use #

Another web server, usually nginx or Apache, already has them. See what it is:

ss -ltnp

Stop it if you don't need it, then run the installer again. For nginx:

systemctl disable --now nginx

If the server hosts other sites, keep it and pick My own nginx in the installer instead: see Use your own nginx.

The disk is full #

Umiji's images need about 2 GB. See what takes the space, and remove old images:

df -h
docker image prune -a

Domain and HTTPS

The panel doesn't open, or the browser warns about the certificate #

The HTTPS certificate isn't there yet. Check these, in order:

  1. The domain points at the server. On your computer, nslookup panel.example.com should show the server's IP. If not, fix its A record.
  2. Ports 80 and 443 are open in your provider's firewall, if it has one.
  3. On Cloudflare, the cloud is grey, or Always Use HTTPS is off.

Caddy keeps trying on its own. Watch it get the certificate:

cd /opt/umiji && docker compose logs -f umiji-caddy

The panel shows 502 Bad Gateway #

The panel is still starting, which takes about 30 seconds, or it stopped. See its state and its log:

cd /opt/umiji && docker compose ps
docker compose logs --tail 50 umiji

The sub page's domain shows nothing #

That's normal. The sub page only answers a user's subscription link, never its bare address. Open a real link from a user's card to test it.

A 502 there means the sub page isn't running on this server. Type umiji, pick Install / update and tick Sub page.

Subscription links show the wrong domain #

Fix SUB_DOMAIN in /opt/umiji/.env, then restart the panel:

cd /opt/umiji && docker compose up -d

Signing in

I forgot the admin password #

On the panel's server, type umiji and pick Owner password. It sets a new password and turns password login back on, in case it was off.

umiji

“Too many sign-in attempts” #

After 10 wrong tries for one username, or 20 from one IP, the panel waits. Try again in 5 minutes.

Nodes

A node stays offline #

The panel can't reach the node's port, 2222 unless you changed it. On the node's server, let the panel's IP in, and open the port in your provider's firewall too:

ufw allow from 203.0.113.10 to any port 2222 proto tcp

Still red? Check that the node runs, and read its log:

docker logs --tail 50 umiji-node

If the log talks about SECRET_KEY, the key was cut off when you copied it. Copy it again from Manual setup and run the installer with node at the end.

The node next to the panel is offline #

The node the installer added as Panel server is reached through Docker's network on the same server. If you turned on the firewall after installing, let Docker's addresses in:

ufw allow from 172.16.0.0/12 to any port 2222 proto tcp

Automatic install fails #

If it stops at SSH, check the IP, the SSH port and the root password. Some providers turn off password logins for root: then use Manual setup instead.

If it stops at the handshake, the node is running but the panel can't reach it: see A node stays offline.

Users and apps

The app can't connect #

Walk the route from the server to the phone:

  1. The node has a green dot on the Nodes page.
  2. The node runs the inbound: under the node's Core configuration, it's ticked.
  3. The inbound's port, like 2083, is open in the node's firewall and your provider's.
  4. The host's Address is the node server's public IP (for Panel server, the panel server's IP, never 172.x) or a domain pointing to it, and its Port is the inbound's.
  5. For REALITY, the Target is a real HTTPS site that the node can reach.
  6. The user is Active, not limited or expired.

After changing something, update the subscription in the app.

The app shows no servers #

A user gets a host only if the host's Host visibility is on and its inbound is in one of the user's internal squads. Check both, then update the subscription in the app.

Keeping it running

How do I update? #

On each server, type umiji and pick Update all. It backs up the panel's database first.

Moving the panel to a new server #

  1. On the old server, type umiji and pick Back up.
  2. Install Umiji on the new server and point the domains at it.
  3. Copy the backup into /opt/umiji/backups/ there, type umiji and pick Restore.

Telegram bots don't answer #

Telegram may be blocked where the panel runs. Add a proxy as TELEGRAM_BOT_PROXY in /opt/umiji/.env, like socks5://172.17.0.1:1080, then restart the panel:

cd /opt/umiji && docker compose up -d

Nothing matches. Try a shorter word, or ask on GitHub.