This is the multi-page printable view of this section. Click here to print.
Prerequisites to setup MyController server
MyController.org 2.x can be installed in different way.
To know more about server setup follow this guide
You can install MyController in two different ways. You can either go with container image or executable binary.
Steps to install on your linux machine with docker
root user.sudo in the beginning of the commands.
mkdir -p /opt/apps/mycontroller/mc_home
mkdir -p /opt/apps/mycontroller/mc_home/secure_share
mkdir -p /opt/apps/mycontroller/mc_home/insecure_share
mycontroller.yaml file
cd /opt/apps/mycontroller
curl https://raw.githubusercontent.com/mycontroller-org/backend/v2.0.0/resources/sample-docker-server.yaml \
--output mycontroller.yaml
IMPORTANT: update your secret on the mycontroller.yaml file. DO NOT USE THE DEFAULT SECRET
secret can between 1 to 32 characters length
This secret used to encrypt your third party password, tokens used on this server
secret: 5a2f6ff25b0025aeae12ae096363b51a # !!! WARNING: CHANGE THIS SECRET !!!
Update influx_database configuration as follows in your mycontroller.yaml
uri - must point to the influxdb host ip address
database:
metric:
disabled: false
type: influxdb
uri: http://192.168.1.21:8086 # must be updated with your host ip address
token:
username:
password:
organization_name:
bucket_name: mycontroller
batch_size:
flush_interval: 5s
Optional - update bus configuration as follows in your mycontroller.yaml, if you plan to use external bus
server_url - must point to the nats.io server ip address.
bus:
type: natsio
topic_prefix: mc_communication_bus
server_url: nats://192.168.1.21:4222 # must be updated with your host ip address
insecure: false
connection_timeout: 10s
Start the MyController server
docker run --detach --name mycontroller \
--publish 8080:8080 \
--publish 8443:8443 \
--publish 9443:9443 \
--volume $PWD/mc_home:/mc_home \
--volume $PWD/mycontroller.yaml:/app/mycontroller.yaml \
--env TZ="Asia/Kolkata" \
--restart unless-stopped \
docker.io/mycontroller/server:2.0.0
Access MyController server Web UI
http://<host-ip>:8080 (example: http://192.168.1.21:8080)https://<host-ip>:8443 (example: https://192.168.1.21:8443)docker logs mycontroller
Ctrl+C
docker logs --follow mycontroller
docker stop mycontroller
docker restart mycontroller
docker stop mycontroller
docker rm mycontroller
Steps to install the executable binary on your linux machine
Download the executable bundle that matches to your operating system architecture
linux-arm - 32 bit ARM Linuxlinux-arm64 - 64 bit ARM Linuxlinux-386 - 32 bit Linuxlinux-amd64 - 64 bit Linuxwindows-386 - 32 bit Windowswindows-amd64 - 64 bit Windowsarm architecture (Raspberry Pi). You can follows this guide for other architecture too.root, you should include sudo in the beginning of the commands. or directly run the commands as root user.
mkdir -p /opt/apps/mycontroller/mc_home # directory to hold data
mkdir -p /opt/apps/mycontroller/executable # directory to hold executable
# create directories to keep image files to show it MyController dashboard
# Example, camera stream image
mkdir -p /opt/apps/mycontroller/mc_home/secure_share
mkdir -p /opt/apps/mycontroller/mc_home/insecure_share
# download the bundle and extract on executable directory
cd /opt/apps/mycontroller
wget https://github.com/mycontroller-org/server/releases/download/v2.0.0/mycontroller-server-2.0.0-linux-arm.tar.gz
tar xzf mycontroller-server-2.0.0-linux-arm.tar.gz --strip-components=1 --directory /opt/apps/mycontroller/executable
mycontroller.yaml) file on the executable directory
$ ls /opt/apps/mycontroller/mc_home # MyController server data location
insecure_share secure_share
$ ls /opt/apps/mycontroller/executable # MyController server executable location
LICENSE.txt logs mcctl.sh mycontroller-server mycontroller.yaml README.txt web_console
IMPORTANT: update your secret on the mycontroller.yaml file. DO NOT USE THE DEFAULT SECRET
secret can between 1 to 32 characters length
This secret used to encrypt your third party password, tokens used on this server
secret: 5a2f6ff25b0025aeae12ae096363b51a # !!! WARNING: CHANGE THIS SECRET !!!
update influxdb configuration as follows in your mycontroller.yaml
uri - must point to the influxdb ip address. if you have installed on the same host, you can leave it as 127.0.0.1database:
metric:
disabled: false
type: influxdb
uri: http://127.0.0.1:8086 # must be updated with your host ip address
token:
username:
password:
organization_name:
bucket_name: mycontroller
batch_size:
flush_interval: 5s
if you plan to use https with ACME(Letsencrypt) follow the detailed guide
Optional - if you plan to use external bus, update bus configuration as follows in your mycontroller.yaml
server_url - must point to the nats.io server ip address. if you have installed on the same host, leave it as 127.0.0.1
bus:
type: natsio
topic_prefix: mc_server
server_url: nats://127.0.0.1:4222 # must be updated with your host ip address
insecure: false
connection_timeout: 10s
Start the MyController server
cd /opt/apps/mycontroller
executable/mcctl.sh start
Access MyController server Web UI
http://<host-ip>:8080 (example: http://192.168.1.21:8080)https://<host-ip>:8443 (example: https://192.168.1.21:8443)executable directory
cd /opt/apps/mycontroller
cat executable/logs/mycontroller.log
Ctrl+C
cd /opt/apps/mycontroller
tail --follow executable/logs/mycontroller.log
cd /opt/apps/mycontroller
executable/mcctl.sh stop
cd /opt/apps/mycontroller
executable/mcctl.sh stop
executable/mcctl.sh start
cd /opt/apps/mycontroller
executable/mcctl.sh stop
rm /opt/apps/mycontroller/executable --recursive --force
TBD
MyController backend configurations are loaded at the time of startup.
Configurations should be in the YAML file format.
Samples are available in the source code repository
mycontroller.yaml file will not be included in the backup for the security reasons.
secret: 5a2f6ff25b0025aeae12ae096363b51a # (1)
analytics: # (2)
enabled: true
web: # (3)
web_directory: /ui
enable_profiling: false
read_timeout: 60s
http:
enabled: true
bind_address: "0.0.0.0"
port: 8080
https_ssl:
enabled: false
bind_address: "0.0.0.0"
port: 8443
cert_dir: /mc_home/certs/https_ssl
https_acme:
enabled: false
bind_address: "0.0.0.0"
port: 9443
cache_dir: /mc_home/certs/https_acme
acme_directory:
email: hello@example.com
domains: ["mycontroller.example.com"]
logger: # (4)
mode: record_all
encoding: console
level:
core: info
web_handler: info
storage: info
metric: warn
directories: # (5)
data: /mc_home/data
logs: /mc_home/logs
tmp: /mc_home/tmp
secure_share: /mc_home/secure_share
insecure_share: /mc_home/insecure_share
bus: # (6)
type: natsio
topic_prefix: mc_production
server_url: nats://192.168.1.21:4222
insecure: false
connection_timeout: 10s
gateway: # (7)
disabled: false
types: []
ids: []
labels:
location: server
handler: # (8)
disabled: false
types: []
ids: []
labels:
location: server
database: # (9)
storage:
type: memory
dump_enabled: true
dump_interval: 10m
dump_dir: "memory_db"
dump_format: ["yaml"] # options: yaml, json
load_format: "yaml"
metric:
disabled: true
type: influxdb
uri: http://192.168.1.21:8086
token:
username:
password:
organization_name:
bucket_name: mycontroller
batch_size:
flush_interval: 5s
query_client_version:
secret is used to encrypt the password, token and other sensitive details in gateways, handlers, etc., and keep encrypted data in the storage database.secret you have update manually the existing passwords and tokens if anyanalytics if enabled, reports anonymous statics to MyController analytics collectorweb holds the web configurationslogger - controls the logs level of a different components.directories - points to custom locations.bus - message bus configurations, will be used for internal communications.gateway - filters to load gateways to this instance.handler - filters to load handlers to this instance.database - defines storage and metric configuration detailsweb:
web_directory: /ui # (1)
documentation_url: http://192.168.1.21:8079/docs/ # (2)
enable_profiling: false # (3)
http: # (4)
enabled: true
bind_address: "0.0.0.0"
port: 8080
https_ssl: # (5)
enabled: false
bind_address: "0.0.0.0"
port: 8443
cert_dir: /mc_home/certs/https_ssl
https_acme: # (6)
enabled: false
bind_address: "0.0.0.0"
port: 9443
cache_dir: /mc_home/certs/https_acme
acme_directory:
email: hello@example.com
domains: ["mycontroller.example.com"]
web_directory - production build of Web Consoledocumentation_url - if you are in a private environment and want to keep the document server locally. Add your documentation server url.enable_profiling - enables GoLang profiling on the http handler at /debug/pprof/http - HTTP handlerhttps_ssl - HTTPS SSL handlerhttps_acme - HTTPS ACME handlerHTTP handler serves the web console and api as un-encrypted.
This setup can be used in a trusted network.
http:
enabled: true # (1)
bind_address: "0.0.0.0" # (2)
port: 8080 # (3)
enabled - can enable or disable the http handler. if no values supplied, will be treated as disabledbind_address - IP address to bind, 0.0.0.0 - binds to all the available network interfaces.port - listening port numberHTTPS SSL handler serves the web console and api as encrypted.
You can use self signed certificate or CA signed certificate.
You can use this handler to access the web console on the untrusted networks
https_ssl:
enabled: false # (1)
bind_address: "0.0.0.0" # (2)
port: 8443 # (3)
cert_dir: /mc_home/certs/https_ssl # (4)
enabled - can enable or disable the https ssl handler. if no values supplied, will be treated as disabledbind_address - IP address to bind, 0.0.0.0 - binds to all the available network interfaces.port - listening port numbercert_dir - certificate and key files location.https_ssl operates in two modes.
If there is no custom.crt and custom.key found on the cert_dir location MyController generates a crt and key files and stores on cert_dir location. Auto generated file names will as mc_generated.crt and mc_generated.key.
Auto generated certificate details:
If you want to change these details, you have to generate a certificate manually as mentioned in Custom certificate
If you want to use your custom certificates, you have to place your files on the cert_dir location.
The name of the files must be as custom.crt and custom.key
To generate self signed certificate there are multiple options available. Here is a quick sample,
openssl genrsa -out custom.key 2048
openssl req -new -x509 -sha256 -key custom.key -out custom.crt -days 365
custom.crt and custom.key files are present in the cert_dir, it get the higher precedence than the auto generated files.
Automated Certificate Management Environment (ACME) is a standard protocol for automating domain validation, installation, and management of X.509 certificates.
Letsencrypt is popular free certificate provider.
This handler can take care of the life cycle of the certificate. That is to get the certificate first time and subsequence renewals.
tls-alpn-01. Extra port is not required.
To know more about tls-alpn-01 visit Letsencrypt guidehttps_acme port. This port should be reachable on public ip of 443 port. acme challenge will be verified only on 443 port.https_acme:
enabled: false # (1)
bind_address: "0.0.0.0" # (2)
port: 9443 # (3)
cache_dir: /mc_home/certs/https_acme # (4)
acme_directory: # (5)
email: hello@example.com # (6)
domains: ["mycontroller.example.com"] # (7)
enabled - can enable or disable the https acme handler. if no values supplied, will be treated as disabledbind_address - IP address to bind, 0.0.0.0 - binds to all the available network interfaces.port - listening port numbercache_dir - certificate and related files received from the provider will be stored on this directory.acme_directory - ACME provider directory url, if you leave it blank the default will be https://acme-v02.api.letsencrypt.org/directoryemail - email address used to get the certificate from the providedomains - You can have single or multiple domainslogger:
mode: record_all # (1)
encoding: console # (2)
enable_stacktrace: false # (3)
level: # (4)
core: info
web_handler: info
storage: info
metric: warn
mode - supports two modes.
record_all - prints the detailed information about the log fieldssampled - prints the restricted information about the log fields and not all the logsencoding - log encoding format
console - suits for console displayjson - prints logs in json format, suits for processing with external toolsenable_stacktrace - enables stack trace of the errorlevel - restrict the log level. supported levels: debug, info, warn, error, fatal.
You can restrict the log level to a specific service.
core - entire system log level. This is applicable for gateway service too.web_handler - http handlers log levelstorage service log levelmetrics service log leveldirectories:
data: /mc_home/data # (1)
logs: /mc_home/logs # (2)
tmp: /mc_home/tmp # (3)
secure_share: /mc_home/secure_share # (4)
insecure_share: /mc_home/insecure_share # (5)
MyController uses these directories to keep configurations, logs, and temporary files.
data - keeps all configurations on this location. in-memory database, firmware, etc.,logs - keeps gateway logs and system logstmp - used as a temporary location for MyController servicessecure_share - you can keep custom files on this location. This location can be accessed via MyController instance url, http://mycontroller-ip:8080/secure_share. It needs authentication. access token can be supplied via header or on the url.insecure_share - you can keep custom files on this location. This location can be accessed via MyController instance url, http://mycontroller-ip:8080/insecure_share. It is open to everyone. Authentication not requiredbus:
type: natsio # (1)
topic_prefix: mc_production # (2)
server_url: nats://192.168.1.21:4222 # (12)
insecure: false # (3)
connection_timeout: 10s # (4)
type - There are two type of message bus available.
embedded - internal message bus. You cannot include external gatewaynatsio - external message bustopic_prefix - A natsio message bus can be used for different applications.
Based on this topics we can separate a specific MyController instance.server_url - natsio server urlinsecure - allow or disallow insecure connectionsconnection_timeout - connection establishment timeoutgateway:
disabled: false # (1)
types: [] # (2)
ids: [] # (3)
labels: # (4)
location: server
We can restrict to load a specific gateway to this service.
disabled - enables or disables gateway servicetypes - filter specific gateway typesids - filtered by list of gateways idlabels - filtered based on the labels. detailed guidehandler:
disabled: false # (1)
types: [] # (2)
ids: [] # (3)
labels: # (4)
location: server
We can restrict to load a specific handler to this service.
disabled - enables or disables handler servicetypes - filter specific handler typesids - filtered by list of handlers idlabels - filtered based on the labels. detailed guideYou can define you storage and metric database configurations
database:
storage:
# storage database configurations
metric:
# metric database configurations
MyController needs two type of databases.
MyController supports two type of storage databases
In memory is a special database designed by MyController org. It keeps all the configuration data in the memory(RAM). Dumps all the data into the disk on a specified interval. When MyController start up, loads all the data from the disk to memory.
database:
storage:
type: memory # (1)
dump_enabled: true # (2)
dump_interval: 10m # (3)
dump_dir: "memory_db" # (4)
dump_format: ["yaml", "json"] # (5)
load_format: "yaml" # (6)
type should be memorydump_enabled - enable or disable sync to disk feature. Copies in memory entities into diskdump_interval - how long once the sync should happen.dump_dir - directory used to dump entities from memory. default: memory_dbdump_format - supports yaml and/or json formats.load_format - even though you can dump entities on yaml and/or json format. at the time of startup, only one format can be used. Make sure you are using this format on the dump_formatMyController supports MongoDB local or cloud version.
type: mongodb # (1)
database: mcdb # (2)
uri: mongodb://192.168.1.21:27017 # (3)
type should be mongodbdatabase - name of the database in your MongoDBuri of the database. supports cloud database format too.MyController supports two type of metric databases
MyController uses InfluxDB to keep the metrics data. It can be local InfluxDB instance or can be in the cloud.
MyController supports InfluxDB 1.8.4 or above versions.
Flux query supports for InfluxDB 1.8.x and InfluxDB 2.x,
however there is an issue on ARM architecture in mean and query functions
As a workaround, MyController uses two type of InfluxDB query clients.
database:
metric:
disabled: false # (1)
type: influxdb # (2)
uri: http://192.168.1.21:8086 # (3)
token: # (4)
username: # (5)
password: # (6)
organization_name: # (7)
bucket_name: mc_db # (8)
query_client_version: # (9)
batch_size: # (10)
flush_interval: 1s # (11)
disabled if you want to disable metric databasetype should be influxdburi is the database connection URItoken - authentication token used in InfluxDB 2.xusername - authenticate using username and passwordpassword - authenticate using username and password. If username specified password is a mandatory field.organization_name - used in InfluxDB 2.xbucket_name - In influxdb 1.x it is a database name. In influxdb 2.x it is called bucketquery_client_version - MyController uses two type of query clients.
It is recommended to keep it blank. MyController can choose automatically based the the database version used.
However we can override the automatic selection by providing one for the option,
v1 - InfluxDB 1.8.xv2 - InfluxDB 2.xbatch_size - sends the metrics to InfluxDB when meets the batch sizeflush_interval - sends the metrics to InfluxDB when meets the intervaldatabase:
metric:
disabled: false
type: influxdb
uri: https://eu-central-1-1.aws.cloud2.influxdata.com
token: VGhpcyBpcyBmYWtlIHRva2VuLCB0YWtlIHlvdXIgZnJvbSBNb25nb0RCIGNsb3VkCg==
username:
password:
organization_name: example@example.com
bucket_name: mc_bkt
query_client_version:
batch_size:
flush_interval: 1s
MyController gateway configurations are loaded at the time of startup.
Configurations should be in the YAML file format.
Refer backend configuration detailed guide to know about the configurations
# This secret should be same as given in the server configuration file.
secret: 5a2f6ff25b0025aeae12ae096363b51a
directories:
data: /mc_home/data
logs: /mc_home/logs
tmp: /mc_home/tmp
logger:
mode: record_all
encoding: console
level:
core: info
storage: info
metric: warn
bus:
type: natsio
topic_prefix: mc_production
server_url: nats://192.168.1.21:4222
insecure: false
connection_timeout: 10s
gateway:
disabled: false
types: []
ids: []
labels:
location: external_gw1