oci-helper: a self hosted panel for running Oracle Cloud instances

A panel for one cloud, scoped to the tasks that panel is for

oci-helper, nicknamed Y探长, is described as a lightweight OCI management panel built on the Oracle OCI SDK with a Spring Boot 3 backend on JDK 21, SQLite for storage, a Vue 2 frontend, and Docker for packaging. The claim is that you can deploy it with one script and without installing anything on the host.

The feature list is where the project's actual shape becomes clear, and it is long. Instance configuration changes, boot volume configuration, attaching IPv6, opening all ports in the security list, listing instances and boot volumes, quota queries, tenant management, and one click updates are all in there.

Several features are marked as the highlights in the documentation. One enables free AMD instances with a 500 Mbps downlink. Another automatically rescues and shrinks the boot volume, with 47GB as the default. Another gives minute level real time traffic statistics. Another offers an IP information page at a per-server address, and a home page with a world map of servers.

The one worth pausing on is public IP replacement by CIDR range. The documentation says you can replace an instance's public IP with one matching several given CIDR ranges, that requests which fail because of rate limiting are simply ignored so they do not affect the next attempt until an IP in the desired range is obtained, and that Cloudflare DNS records can be updated automatically afterwards.

That combination, switching public IPs repeatedly and rotating DNS to follow, is a capability with a specific purpose and a specific risk, and the project's own notices say as much: it advises using the service on a local network rather than exposing it to the internet, and it disclaims responsibility for accounts being banned because of too frequent booting and IP changes. Read those notices before deploying.

Multi tenant configuration with fuzzy search on every list

The panel is built around the idea that one operator runs several Oracle Cloud tenants, and the data model reflects that.

You can add multiple tenant configurations in bulk, and every paginated list supports fuzzy search and status filtering. A tenant is identified by its credentials, and the panel stores PEM key files in a `keys` directory that the deployment tree shows alongside the configuration file, the database file and the compose file.

Region handling is explicit. The documentation describes supporting multiple region identifiers, with the configuration distinguished by region: if you have four region numbers, you add four configurations that differ only in the region field.

The persistence is deliberately simple. SQLite holds the whole state, in a single `oci-helper.db` file that appears in the deployment directory and in the repository root. There is also an encrypted backup and restore routine, described as enabling a smooth data migration, which is the feature you want if you are moving the panel between hosts.

Task persistence is the other half of the story, and it is the more interesting design decision. The documentation highlights resumable operations: configurations and tasks are saved in the local database, so a service restart continues the running task without needing to be configured again. That property matters for the long running operations the panel performs, and it is also what makes the panel safe to restart mid operation.

One command installs it, and the same command updates it

The deployment story is a single shell command:

bash <(wget -qO- https://github.com/Yohann0617/oci-helper/releases/latest/download/sh_oci-helper_install.sh)

The documentation notes that this command also updates the image and restarts the container without deleting existing configuration, which is why it can serve both as installer and updater.

After the script runs, the panel is reachable at the server address on port 8818, and the account and password can be changed through the script. To change them by hand you edit `/app/oci-helper/application.yml` and restart the container with `docker restart oci-helper`.

The deployment directory after installation looks like this:

root@yohann:/app/oci-helper# tree
.
├── keys                            # 是一个目录，存放所有的pem秘钥文件
├── application.yml                 # 项目配置文件，如需更改网页账号密码在此处更改，并执行 docker restart oci-helper 重启容器
├── docker-compose.yml              # docker-compose部署所需配置文件
├── oci-helper.db                   # 项目数据库文件
└── update_version_trigger.flag     # 注意是一个文件，不是目录，用于版本自动更新

Note that the version update trigger is a file, not a directory, and that it is shared with the watcher container in the compose setup. That is the mechanism behind the automatic update feature: a watcher container watches the flag and the compose file, and the update script triggers a pull and restart by touching the flag.

Logs can be exported with `docker logs oci-helper >> /app/oci-helper/oci-helper.log`, and the documentation reminds you to clean up the Docker logs periodically.

A manual installation path is documented as well, and is explicitly labelled as not recommended. It starts by creating the key directory with `mkdir -p /app/oci-helper/keys && cd /app/oci-helper` and then downloading files from the Releases page.

Behind an Nginx proxy, with the panel bound to loopback

The security guidance in the documentation is specific and worth taking seriously, because the panel holds cloud API keys.

The recommendation is not to expose the service to the public internet, to avoid plain HTTP and to put an Nginx reverse proxy in front of it for HTTPS, and to use key based login on the server so that a brute force SSH attempt cannot leak the API data and keys. The panel itself also supports MFA for its own login, which the documentation is explicit is the panel's own MFA and not the shell provider's.

The compose configuration for that setup is published, and the important line is the port binding. The service is published as `127.0.0.1:8818:8818`, described as the change to make, so the port is only reachable from the server's own network. The same pattern applies to the websockify service on `127.0.0.1:6080:6080`.

That websockify container is there for the VNC connection used in rescue mode. The Nginx configuration proxies a `/myvnc/` path to the websockify service with WebSocket upgrade headers and long timeouts, and proxies everything else to the panel on 8818 with the standard forwarded headers including X-Real-IP, X-Forwarded-For and X-Forwarded-Proto. The timeouts are set to 10800 seconds on both directions.

The guidance is explicit that this configuration is required if you want both HTTPS and VNC access for rescue operations, because without the loopback binding the service would be reachable directly by IP and port. The compose file also mounts the Docker socket into the watcher container, which is what lets the watcher manage the other container.

The Java side, and what the container actually contains

The stack is Java on the backend with a Vue 2 frontend, built with Maven and packaged with Docker.

The Dockerfile is a two stage build. The builder stage uses `maven:3-eclipse-temurin-21`, copies the source in, runs `mvn clean package -DskipTests`, and copies the resulting jar. The runtime stage is `eclipse-temurin:21-jre-jammy` with openssh-client, lsof, curl and locales installed, and it sets the locale to zh_CN.UTF-8 with the timezone to Asia/Shanghai.

Two details in that runtime image are about the panel's function rather than its packaging. The SSH client is there because the panel performs operations over SSH against instances, including the netboot rescue flow described as a Cloud Shell style console. The `/root/.ssh/config` written into the image enables the older ssh-rsa host key algorithms and pubkey accepted key types, which is what old OCI images need.

The container exposes port 8818 and the entrypoint runs the jar with two `--add-opens` flags for `java.base/java.net` and `java.base/sun.net.www.protocol.https`, piping output through tee into `/var/log/oci-helper.log`. Those opens are needed because the panel makes HTTPS calls to the OCI endpoints and to whatever API it proxies.

The documented platform requirements are OpenJDK 21 or newer, Spring Boot 3, Vue 2, SQLite 3, Maven 3 and Docker 28 or newer.

The backend uses JDK 21 virtual threads, which the documentation credits for handling concurrent requests with lower resource use, and that is a genuine fit for a workload that is mostly waiting on Oracle Cloud API calls.

Where this panel is not the right tool

Three boundaries are worth stating.

The first is that this is an Oracle Cloud tool. The panel is built on the OCI SDK and the workflows are OCI workflows: boot volumes, security lists, IPv6 attachment, quotas, shape changes. If your estate spans AWS, GCP and Azure as well, this will not be the console you use, and there is no indication that a multi cloud abstraction is planned.

The second is the security model, which is a local network tool by design. The documentation's own advice is to keep it on a LAN, behind a reverse proxy, with key based server access and MFA on the panel itself. The panel holds PEM keys that grant access to your cloud tenants and a database of every tenant configuration and task, so a compromise of that host is a compromise of the cloud accounts. If you need role based access control, audit logging, or the ability to expose the panel to a wider group, you have to build that around it.

The third is the operational risk of the features themselves. Replacing public IPs on a schedule and retrying instance boots is the sort of activity that providers notice, and the documentation states plainly that it is not responsible for accounts being banned for excessive boot and IP change frequency. Anything you deploy with these features enabled is your responsibility under your provider agreement.

The alternative worth naming is the Oracle Cloud CLI and the web console. They are slower and less convenient for the batch workflows, and they do not persist a task queue across restarts, but they are the vendor's own tooling, they carry no third party in your credential path, and using them keeps you well inside the provider's expected usage pattern. For occasional work, that is the right trade.

Editorial conclusion

Adopt oci-helper if you run several Oracle Cloud tenants and want instance lifecycle, network rules, boot volumes, public IP and DNS management behind one local web interface with everything persisted in SQLite. Do not adopt it if you need a general cloud management platform, because it targets Oracle Cloud specifically, and read the network guidance before you deploy because the documentation says to keep it on a local network behind an HTTPS reverse proxy. Verify first which tenant credentials you can supply as PEM keys, that your account is allowed the instance shapes and boot volumes the panel expects, and that the free tier instance and IP rotation features fit your provider agreement.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. Yohann0617/oci-helper on GitHub