moctl: On-Prem Service Management Guide

---

The miniOrange On‑Premise Identity Server includes a command‑line utility called moctl that helps administrators manage and operate the identity platform more efficiently.

It is intended for IT teams and system administrators who have the miniOrange 5.0.0 installed on a server, or who want to deploy moctl fresh. This guide covers deployment, service management, logs, diagnostics, and troubleshooting.

Prerequisites

Here’s a list of elements you would need before installation, deployment, and operations.

The expected environments that you would need are:

• Root or sudo access
• Product path accessible at /opt/tomcat/latest
• systemd services in mo-idp-*.service format
• Runtime config at /etc/mo-idp-server.env (primary config on deployed servers)

Installation, Configuration & Operations

1. Installation and Deployment

• If moctl is not yet on the server, transfer and install the package:

Transfer the package

          scp moctl.zip admin@<server-ip>:/opt/
        

Extract and install

          
            cd /opt
            ├── unzip moctl.zip
            ├── cd /opt/moctl
            ├── sudo bash install-moctl.sh
          
        




Note:

install-moctl.sh reads /etc/mo-idp-server.env if it exists and updates the runtime config accordingly.

The user is setting up the following:

• Executable: /usr/local/bin/moctl
• Support files: /opt/miniorange/moctl
• Runtime config: /etc/mo-idp-server.env (created or updated)

2. Validation of the Installed Package

• Confirm that the files are in place.

          
            which moctl
            ls -l /usr/local/bin/moctl
            cat /etc/mo-idp-server.env
        

• Confirm that the tool responds correctly.

          
            moctl version
            moctl service status
            moctl diagnose full
          
        

3. Service Management

• The next step is to check the status.

          moctl service status
        




Status	Meaning
Running	Service is active and healthy.
Registering	Active and Eureka-managed, still registering. Wait 30–60 s.
Stopped	Service is inactive.
Failed	Service crashed. Check logs immediately.

Note:

In 5.0.0 eurekaserver and miniOrange run outside Eureka. They will show running, never registering.



• Start / Stop / Restart

Command	What it does
moctl service start	Start all services in the correct order.
moctl service stop	Stop all services in reverse order.
moctl service restart	Restart all services.
moctl service start gatekeeper	Start a single named service.
moctl service restart miniorange	Restart a single named service.




Note:

Core services start first : configserver → eurekaserver → gatekeeper → miniOrange. Secondary services follow automatically. Running moctl service or moctl diagnose without a subcommand prints suggestions.

4. Log Access & Monitoring

Command	What it does
moctl log miniorange	Start all services in the correct order.
moctl log miniorange -f Follow	Follow logs live (Ctrl+C to stop).
moctl log miniorange -n 500	Show last 500 lines.
moctl log miniorange --since 1h	Show logs from the past hour.
moctl log gatekeeper --since 30min	Show logs for any named service.

5. Diagnostics

• In this step, you can run a full check.

          moctl diagnose full
        



• Checks: service state, core ports, memory, disk, Nginx, Java, env file, and symlink.

Command	What it does
moctl diagnose services	Service states only.
moctl diagnose ports	Core port availability.
moctl diagnose resources	Memory and disk usage.
moctl diagnose deps	Nginx, Java dependencies.
moctl diagnose	Show available subcommands and usage help.

6. System and JVM Inspection

Command	What it does
moctl system memory	Show memory usage
moctl system cpu	Show CPU usage
moctl system disk	Show disk usage
moctl jvm miniorange	JVM version, heap, flags, threads, file descriptors

7. Recommended Workflows

• Routine check during logins

          
            moctl diagnose full
            moctl service status
          
        



• Investigating a service issue.

          
            moctl service status
            moctl log miniorange --since 30min  
          
        



• Restart the affected service, and then confirm recovery.

          
            moctl service restart gatekeeper
            moctl service status
            moctl diagnose services  
          
        




Note:

Prefer a single-service restart over a full restart whenever possible.

8. Troubleshooting

For all your troubleshooting issues, here’s what you can do:

• moctl not found

          
          ls -l /usr/local/bin/moctl  
            echo $PATH
          
        



• If missing, then rerun the installer

            
            sudo bash install-moctl.sh
          



• Services not detected

          
          systemctl list-unit-files 'mo-idp-*.service'
        



• Expected service names:
• mo-idp-configserver.service
• mo-idp-eurekaserver.service
• mo-idp-gatekeeper.service
• mo-idp-miniorange.service
• If the product path is incorrect

          
          cat /etc/mo-idp-server.env
          ls -ld /opt/tomcat/latest
        




Correct the path in /etc/mo-idp-server.env and rerun the installer.

• Service is stuck in registering

          
          moctl diagnose services  
          moctl log gatekeeper --since 30min  
          curl -u registry_client:'Eureka2025_Client!' http://localhost:8070
        




Check: Eureka availability, credentials in /etc/mo-idp-server.env, and startup errors in logs.

Note:

Scheduler and miniOrange are not Eureka-managed in 5.0.0; they will never show registering. If you see registering on these services, it indicates a display or config issue.



• Env file or symlink missing

            
            test -f /etc/mo-idp-server.env && echo ok
            test -L /opt/tomcat/latest && readlink -f /opt/tomcat/latest  
          




Correct the failing value and rerun the installer. The runtime config at /etc/mo-idp-server.env is the authoritative source.