Umiji

From an empty server to a working connection.

Ten short steps. At the end, one user has a subscription link and their phone is connected through your own server.

  • 10 steps
  • About 30 minutes
  • One command installs it
01
On the server

Install Umiji

One command installs everything. It adds Docker if needed, asks a few questions that each have a ready answer, and if something goes wrong, it tells you how to fix it.

What you need

  • A Linux server with root access. Ubuntu or Debian is easiest.
  • A domain you own, like example.com. The panel and the subscription page each get a name under it.

Umiji has three parts. Each needs at least:

PartMemoryCPUDisk
Panel, where you manage everything2 GB1 core10 GB
Node, which carries your users' traffic1 GB1 core5 GB
Sub page, which your users open512 MB1 core5 GB
All three together2 GB2 cores20 GB

Run all three on one server, or give each part a server of its own. The installer asks what each server should run, so you can add parts later, here or elsewhere.

Point your domain at the server

Add two A records, panel and sub, each with your server's IP as the value. Do it before you install: HTTPS needs them.

Namecheap is shown here. Other companies have the same fields under DNS.

  1. Open Domain List, press Manage next to your domain, then open Advanced DNS.
  2. Press Add New Record and pick A Record. Host panel, value your server's IP. Save it with the green check.
  3. Add another one with host sub and the same IP.
  1. At dash.cloudflare.com, press Onboard a domain, type your domain and pick the Free plan.
  2. Where you bought the domain, replace its nameservers with the two Cloudflare gives you. Wait until Cloudflare says Active.
  3. Open DNS, Records, and add an A record named panel with your server's IP. Click the cloud until it's grey (DNS only), then save.
  4. Add sub the same way.

Keep the clouds grey for now. The orange cloud needs extra settings.

Check it from your computer. The answer should show your server's IP:

nslookup panel.example.com

Run the installer

  1. Log in to the server as root. On Windows, use PowerShell.
    ssh root@203.0.113.10
  2. Run the installer:
    bash <(curl -fsSL https://raw.githubusercontent.com/therewasluna/umiji/main/install.sh)
  3. Pick what this server runs. Panel and Sub page are ticked. To run a node here too, type 3: the installer then adds it to the panel for you. Press Enter.
  4. Type your panel's domain. For every other question, Enter takes the answer in brackets, and at the password it makes a strong one.
  5. Save the username and password it shows at the end.
  What should this server run?
    [x] 1  Panel     where you manage users, nodes and resellers
    [x] 2  Sub page  the page your users open from their link
    [x] 3  Node      carries your users' traffic

  Panel domain, e.g. panel.example.com: panel.example.com
  …
  [5/16] ✓ Panel is running 31s
  [6/16] ✓ Admin account admin created 0s
  [16/16] ✓ Node added to the panel as Panel server 4s

If a step fails, fix what it says and type umiji: it carries on from there. Stuck? See Common issues.

Later: the umiji command

Type umiji on the server for a menu: install more parts, update, move users from another panel, switch the store bots between polling and webhook, back up, restore, reset the admin password, or uninstall. Backups go to /opt/umiji/backups/. They hold everything, so keep them private, and copy them off the server now and then, from your computer:

scp root@203.0.113.10:/opt/umiji/backups/umiji-20261116-141537.tar .
Use your own nginx, or a CDN

The installer's built-in HTTPS (Caddy) needs ports 80 and 443 to itself. If the server already runs other websites, pick My own nginx in the installer, then on the server:

  1. Install nginx and certbot:
    apt install -y nginx certbot python3-certbot-nginx
    If ufw status says active, open the web ports. Keep 3000, 3001 and 3010 closed.
    ufw allow 'Nginx Full'
  2. Open a new config file:
    nano /etc/nginx/sites-available/umiji
    Paste this, with your domains. Keep the sub page's server block only if the sub page runs on this server.
    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }
    
    # The panel reads the visitor's IP from X-Umiji-Real-IP, so nginx sets it and ignores whatever the visitor sent.
    map $remote_addr $umiji_real_ip {
        default $remote_addr;
        # A sub page on another server that reaches the panel at https://panel.example.com sends its own
        # visitors' IPs. Trust it by its IP:
        # 203.0.113.20 $http_x_umiji_real_ip;
    }
    
    # Panel
    server {
        listen 80;
        server_name panel.example.com;
    
        # Bot broadcast photos are up to 10 MB.
        client_max_body_size 20m;
    
        # Backend-tools links carry a short-lived bearer token in the query string.
        location ^~ /api/backend-tools {
            access_log off;
            proxy_pass http://127.0.0.1:3000;
            proxy_http_version 1.1;
            proxy_set_header Host $host;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Umiji-Real-IP $umiji_real_ip;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    
        location / {
            proxy_pass http://127.0.0.1:3000;
            proxy_http_version 1.1;
            proxy_set_header Host $host;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Umiji-Real-IP $umiji_real_ip;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
    
    # Subscription page, if it runs on this server
    server {
        listen 80;
        server_name sub.example.com;
    
        location / {
            proxy_pass http://127.0.0.1:3010;
            proxy_http_version 1.1;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
  3. Turn it on:
    ln -s /etc/nginx/sites-available/umiji /etc/nginx/sites-enabled/
    rm -f /etc/nginx/sites-enabled/default
    nginx -t && systemctl reload nginx
  4. Get the certificates. Certbot adds HTTPS to the file and renews them on its own; the second command checks that renewal works.
    certbot --nginx -d panel.example.com -d sub.example.com
    certbot renew --dry-run

The panel only answers over HTTPS, so it won't load until certbot has run. nginx always writes X-Umiji-Real-IP itself, so nobody can fake the IP the panel sees.

Behind a CDN, like Cloudflare's orange cloud: set Cloudflare's SSL/TLS mode to Full (strict), then list the CDN's IP ranges, or every visitor shares one IP and one login limit. With Caddy, remove the # from the six lines at the top of /opt/umiji/caddy/Caddyfile, list them there, run docker compose restart umiji-caddy in /opt/umiji, and turn off Cloudflare's Always Use HTTPS. With nginx, add this at the top of the file, one line per range from cloudflare.com/ips:

set_real_ip_from 173.245.48.0/20;
set_real_ip_from 2400:cb00::/32;
# ...the other ranges
real_ip_header X-Forwarded-For;
real_ip_recursive on;

Nodes behind a CDN need their own setup: see IP limit behind a CDN.

Prefer to install without the installer? DEPLOY.md has every step by hand.

02
Panel · first visit

Sign in

  1. Open https://panel.example.com and sign in with the username and password the installer showed.
  2. Read and accept the disclaimer that appears on your first visit.
The Umiji sign-in page: the Umiji wordmark, a username and password field and a Sign in button.
The sign-in page. This is how you get back in.

The sub page

Left Sub page ticked? Then it's already running at https://sub.example.com. Opened on its own it shows nothing; it only answers your users' links, which you'll have in step 9.

To run it on a server of its own instead, point sub at that server, then:

  1. In the panel, go to Umiji Settings, API Tokens, press Create API token, pick the Subpage preset and copy the token.
  2. On that server, run the installer with sub at the end and paste the token when asked:
    bash <(curl -fsSL https://raw.githubusercontent.com/therewasluna/umiji/main/install.sh) sub
  3. At the end it shows three commands. Run them on the panel's server.
03
Menu › Config Profiles

Create a config profile

A config profile is the Xray setup your nodes run. It holds the inbounds, the ports your users connect to. Most setups need just one.

  1. Go to Config Profiles and press Create.
  2. Name it, like Reality, and press Create.
  3. Open the new profile. It opens in the Visual editor.
The Creation dialog on the Config Profiles page, with the profile name Reality typed in.
Name the profile. You can change the whole Xray config afterwards.
04
Config profile › Inbounds

Add a VLESS inbound with REALITY

VLESS with REALITY is a good first inbound. It needs no certificate, and to anyone watching it looks like a visit to a real website.

  1. In the Inbounds section, press New inbound and pick VLESS. It's added on port 2083, and a red dot shows what's left to fill in.
The New inbound dialog, listing protocols: VLESS, Trojan, Shadowsocks, Hysteria 2, MTProto, Mixed, HTTP, Tunnel, WireGuard and TUN.
The new inbound VLESS_2083 open on its General tab: tag, protocol VLESS, listen 0.0.0.0 and port 2083.
Pick a protocol, then fill in the new inbound's tabs.
  1. Open the Security tab. The keys are already made for you.
  2. In Target, enter a real HTTPS site that isn't yours, with its port, like www.example.org:443.
  3. In Server names, enter that site's domain, like www.example.org, and press Save.
The Security tab set to REALITY: Target and Server names are empty and marked red, Private key and Short IDs are already filled in.
Only Target and Server names are left.
05
Menu › Nodes

Add a node

A node is a server that runs Xray with your profile.

Ticked Node in the installer? It's already on the Nodes page as Panel server. Open it, press the pencil under Core configuration, pick your profile, tick the inbound from step 4, save the choice with the disk icon and press Save. Then skip to step 6.

For a node on another server, Umiji installs it for you over SSH:

  1. Go to Nodes and press Create. Automatic install is selected.
  2. Fill in an Internal name, the Country, the Server IP and its Root password.
  3. Press Next. Under Core configuration, pick your profile and tick the inbound from step 4.
  4. Press Install node and wait for the green dot.
The Create node dialog on the Automatic install tab, with name Frankfurt-3, server IP 203.0.113.24, node port 2222, a root password and SSH port 22.
The root password is used once to log in over SSH. It's never stored.

Open the ports in the node's firewall: the inbound's port (2083) for your users, and on a separate server the node port (2222) for the panel.

Rather not give the root password? Pick Manual setup, copy the Secret Key, and run the installer with node at the end on the node's server:

bash <(curl -fsSL https://raw.githubusercontent.com/therewasluna/umiji/main/install.sh) node
The Nodes page: totals for speed, users online and online nodes, then each node with its address, traffic and status.
A connected node shows a green dot and live load.
06
Menu › Hosts

Create a host

A host is what users see in their app: a name and the address to connect to.

  1. Go to Hosts, press Create and turn on Host visibility.
  2. In Remark, write the name users will see. A flag emoji at the start, like 🇩🇪 Germany, shows as a flag.
  3. Press No inbound selected, open your profile, pick the inbound from step 4 and save the choice with the disk icon.
  4. In Address, enter the node server's public IP, the one you SSH into, or a domain pointing to it. For Panel server that's your panel server's IP, not the 172.x address on the Nodes page. Set Port to the inbound's port, then Save.
The inbound picker over the New host drawer, listing config profiles with how many of their inbounds are chosen.
The New host drawer filled in: remark Germany with a flag, the chosen profile and inbound, address de.example.com and port 443.
Pick the inbound, then give the host a name and an address.
07
Menu › Internal Squads

Make an internal squad

An internal squad decides which inbounds its users may use.

  1. Go to Internal Squads, press Create and name it, like Germany.
  2. Open the squad, expand your profile, tick the inbound from step 4 and press Save.
The Edit internal squad drawer for Germany: members and inbound counts, then each config profile with how many of its inbounds are in the squad.
Each profile shows how many of its inbounds are in the squad, like 2 / 4.
08
Menu › Users

Create a user

  1. Go to Users, press Create and enter a Username.
  2. Set a Traffic limit (0 means unlimited) and the Expiry date.
  3. Under Internal squads, tick the squad from step 7, then press Create.
The Create user dialog: username, Telegram ID and email on the left, traffic limit and reset strategy on the right.
Further down the Create user dialog: HWID device limit and tag on the left, expiry date and the Germany internal squad ticked on the right.
Limits first, then access: the expiry date and the squads.
09
Users › the user

Share the subscription link

Every user has one personal subscription link. It keeps working as you add or change servers.

  1. Open the user and copy the Subscription URL, or show its QR code.
  2. Send it to the user. Treat it like a password: anyone with the link can use it.
A user's details: status Active, traffic used out of the limit, expiry date, last seen, and the Subscription URL with a copy button.
The user's card: status, usage, expiry and the link to share.
10
On the user's phone

Connect from a phone

  1. Open the link on the phone. The subscription page shows the traffic left and the apps for that phone.
  2. Install an app, like Happ or v2rayNG, with the buttons under App Installation.
  3. Press Add Subscription, pick 🇩🇪 Germany in the app and connect.
The subscription page on a phone: the user's name and Active status, traffic used drawn as a tide, and the expiry date.
The Installation section for Android: app tabs for Happ, FlClashX, Clash Meta and v2rayNG, install buttons, then Add Subscription and Connect and use.
The top shows what's left. The installation steps change with the platform and the app.

Can't connect? The app can't connect lists what to check.