A process manager with a web dashboard to access console and files remotely.
Octyne allows running multiple apps on a remote server and provides a web dashboard and HTTP API to manage them. It features the ability to access files and terminal input/output remotely over HTTP. This lets you host apps like web servers, game servers, or bots, without needing to use unfriendly tools like SSH or screen to manage them.
Octyne's built-in Web UI is developed as part of the Ecthelion project. Octyne's HTTP API is fully documented as well.
You can follow these recipes to quickly set up Octyne for various use cases:
Contributions to add more recipes are welcome!
- Download the latest version of Octyne from GitHub Releases for your OS and CPU.
- Place octyne in a folder (on Linux/macOS/*nix, mark as executable with
chmod +x <octyne file name>). - Create a
config.jsonnext to Octyne (see the configuration section for details). - Run
./<octyne file name>in a terminal in the folder to start Octyne. Anadminuser will be generated for you. - You can now access the Octyne web dashboard at
http://<your server's IP>:42069! - Install octynectl to manage Octyne from the terminal. Additionally, make sure to setup HTTPS!
You might want to use systemd on Linux to start/stop Octyne automatically for you.
To get the current Octyne version, you can run ./octyne --version or ./octyne -v. This does not account for development builds.
Create a file named octyne.service in /etc/systemd/system/ with the following content:
octyne.service
[Unit]
Description=Octyne
After=network.target
StartLimitIntervalSec=0
[Service]
Type=simple
Restart=on-failure
RestartSec=1
# Replace `abcxyz` with your Linux account username.
User=abcxyz
WorkingDirectory=/home/abcxyz/octyne/
# Install Octyne to /usr/local/bin/ to avoid issues with SELinux on Red Hat-based distros.
# If using SELinux, run `sudo restorecon /usr/local/bin/octyne` after moving the binary.
ExecStart=/usr/local/bin/octyne
[Install]
WantedBy=multi-user.targetThen simply run sudo systemctl enable --now octyne.service to enable and start Octyne.
Octyne relies on the config.json and users.json files in the current working directory to get configuration from.
The path to these files can be customised using the --config=/path/to/config.json and --users=/path/to/users.json CLI flags.
This file contains Octyne's settings, such as all the apps Octyne should start, Redis support for authentication, etc.
NOTE: Octyne supports comments and trailing commas in the config.json file, they don't need to be removed.
Example config.json file:
Full config.json documentation
{
"port": 42069, // optional, default is 42069
"webUI": {
// optional, default true, whether the Octyne Web UI should be enabled
// NOTE: if enabled, the API endpoints will move to /api
// and the web UI will be available at /
"enabled": true,
},
"unixSocket": {
"enabled": true, // enables Unix socket API for auth-less actions by locally running apps e.g. octynectl
"location": "", // optional, if absent, default is TMP/octyne.sock.PORT (see API.md for details)
"group": "" // optional, sets the socket's group owner, if absent, default is current user's primary group
},
"redis": {
// whether Octyne should use Redis for authentication, mainly useful for multi-node setups
// to show them in the same Web UI and share user accounts/login sessions.
// Redis will also persist login sessions across restarts.
"enabled": false,
"url": "redis://localhost", // link to Redis server
"role": "primary" // role of this node, primary or secondary
// note: there should be 1 primary node to manage/authenticate users in a multi-node setup!
},
"https": {
"enabled": false, // whether Octyne should listen using HTTP or HTTPS
"cert": "/path/to/cert.pem", // path to HTTPS certificate
"key": "/path/to/key.pem" // path to HTTPS private key
},
"logging": {
"enabled": true, // whether Octyne should log actions
"path": "logs", // path to log files, can be relative or absolute
"actions": {} // optional, disable logging for specific actions, more info below
},
"servers": {
"test1": { // each key has the name of the server
"enabled": true, // optional, default true, Octyne won't auto-start when false
"directory": "/home/test/server", // the directory in which the server is located
"command": "java -jar spigot-1.12.2.jar" // the command to run to start the server
}
}
}Contains users who can log into Octyne. This file is automatically generated on first start with an admin user and a generated secure password which is logged to terminal. You can perform account management via Octyne Web UI, Ecthelion, octynectl or other such tools. Modifying this file manually is not recommended!
Note: Actions performed locally using the Unix socket API by apps like octynectl are logged as being performed by the @local user, avoid using this username. Apps running on your PC under the same user as Octyne can use this API without a username or password.
Note: Fine-grained control over logging is currently experimental. Therefore, action names may change in any version, not just major versions. However, we will generally try to avoid this in the interest of stability.
By default, Octyne will log all actions performed by users. You can enable/disable logging for specific actions by setting the action to true or false in the logging.actions object in config.json. For example, to disable logging for auth.login and auth.logout, your actions object would be:
"actions": {
"auth.login": false,
"auth.logout": false
}- Authentication (
auth):login,logout - Configuration (
config):reload,view,edit - Account management (
accounts):create,update,delete - Server management (
server):- Top-level actions:
start,stop,kill - Console (
server.console):access,input - Files (
server.files):upload,download,createFolder,delete,move,copy,bulk,compress,decompress
- Top-level actions:
HTTPS ensures end-to-end secure transmission. Using a reverse proxy like Caddy, Apache or nginx makes it easy to setup HTTPS, and allows you to setup rate limits (not yet built into Octyne).
If you are unfamiliar with web servers, Caddy is the simplest way to set up HTTPS, as it automatically obtains and renews certificates for you.
Sample configs for nginx and Apache are provided below too. You must setup HTTPS yourself with these web servers (Certbot is an easy way to do so).
Simply run caddy reverse-proxy --from :42069 --to :8000 to setup Octyne with HTTPS on port 8000! For more advanced setups e.g. combining Octyne with standalone Ecthelion, read the Caddy documentation.
location /octyne {
rewrite /octyne/(.*) /$1 break;
proxy_pass http://127.0.0.1:42069;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# Adjust this as necessary for file uploads:
client_max_body_size 1024M;
# Required for WebSocket functionality to work:
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
}
# Ecthelion (this section is needed ONLY if using Ecthelion standalone)
location /console {
# Remember to set the basePath in Ecthelion's config.json to /console (or whatever you pick)!
proxy_pass http://127.0.0.1:3000;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}Note: Ensure mod_proxy is loaded.
<VirtualHost *:443>
# Octyne
Protocols h2 h2c http/1.1
ProxyPassMatch ^/octyne/(server/.*/console)$ ws://127.0.0.1:42069/$1
ProxyPass /octyne http://127.0.0.1:42069
ProxyPassReverse /octyne http://127.0.0.1:42069
# Ecthelion (this section is needed ONLY if using standalone Ecthelion)
# Remember to set the basePath in Ecthelion's config.json to /console (or whatever you pick)!
ProxyPass /console http://127.0.0.1:4200/console
ProxyPassReverse /console http://127.0.0.1:4200/console
</VirtualHost>
{ "servers": { "minecraft1": { "enabled": true, "directory": "/home/user/minecraft1", "command": "java -Xmx1024M -Xms1024M -jar spigot.jar nogui" }, "minecraft2": { "enabled": true, "directory": "/home/user/minecraft2", "command": "java -Xmx1024M -Xms1024M -jar spigot.jar nogui" } } }