We are currently working on OpenRemote Manager v3, a concise 100% open source IoT platform. This is beta software.
Before following this quickstart make sure you have prepared your environment. There are three options how to start with OpenRemote:
- Starting OpenRemote with images from Docker Hub, easiest for working with the default setup;
- Starting OpenRemote with source-build images, required for developers;
- Starting OpenRemote with Openremote CLI, in beta and only tested on MacOSX.
After that you can use the openremote manager UI.
1. Starting OpenRemote with images from Docker Hub
Use this methods if you want the easiest way to set up OpenRemote locally and use the webapp as an admin user. We publish Docker images to Docker Hub. First clone or download our source code. Execute the following command from the checked out root project directory:
To run OpenRemote using Docker Hub images:
docker-compose up --no-build
To run OpenRemote is swarm mode, which uses Docker Hub images:
docker stack deploy --compose-file mvp/swarm-docker-compose.yml openremote
you don't need to pull or build images in this case, docker swarm mode does this automatically.
2. Starting OpenRemote with source-build images
Alternatively you can build the Docker images locally from source, please see here for required tooling and checkout the openremote project. This method is advised for developers who want to contribute to the project, or customize their local deployment. Let's first get the default manager running. Build the code from the root project directory:
./gradlew clean installDist
Next, if you are using Docker Community Edition build the Docker images and start the stack with:
docker-compose up --build
A first build will download many dependencies (and cache them locally for future builds), this can take up to 30 minutes.
3. Starting OpenRemote with command-line-interface CLI (beta)
or) is a command line tool which can be used for installing an instance of OpenRemote stack on local machine. In this method you won't have to pull the openremote repository. You should already have
docker-compose installed. Note that this method is in beta.
pip3 install -U openremote-cli openremote-cli -V
There is also docker image provided:
docker run --rm -ti openremote/openremote-cli <command>
Note that the image ENTRYPOINT is set to the openremote-cli command (the same way as amazon/aws-cli docker image) therefore
docker run --rm -ti openremote/openremote-cli -V is equivalent to
Deploy on localhost
or deploy --action create
For Windows machines use these commands if
or deploy --action create does not execute properly:
docker volume create openremote_deployment-data docker volume rm openremote_postgresql-data docker run --rm -v openremote_deployment-data:/deployment openremote/deployment:latest wget -nc https://github.com/openremote/openremote/raw/master/swarm/swarm-docker-compose.yml docker swarm init docker-compose -f swarm-docker-compose.yml -p openremote up -d
Deploy on AWS
openremote-cliAWS profile. If you have Id and AWS secret key, you can use following command:
or configure_aws --id <id> --secret <secret> -d -v
At the moment the default region must be set to eu-west-1 (Ireland), this is done by the OpenRemote-cli. This can be could be changed using aws-cli (not recommended):
aws configure --profile=openremote-cli
Deploy the stack:
or deploy --provider aws --dnsname test.mvp.openremote.io -v
Remove the stack and clean resources:
or deploy -a remove --provider aws --dnsname test.mvp.openremote.io -v
Deploy the stack using docker on Mac/Linux:
docker run --rm -ti -v ~/.aws:/root/.aws openremote/openremote-cli deploy --provider aws -v --dnsname test-osx.mvp.openremote.io
Deploy the stack using docker on Windows:
docker run --rm -ti -v %userprofile%\.aws:/root/.aws openremote/openremote-cli deploy --provider aws -v --dnsname test-win.mvp.openremote.io
Using the OpenRemote manager
When all Docker containers are ready, you can access the OpenRemote UI and API with a web browser (if you are using Docker Toolbox replace
OpenRemote Manager, master realm: https://localhost
Smart City realm with Demo setup: https://localhost/main/?realm=smartcity
You must accept and make an exception for the 'insecure' self-signed SSL certificate. You can configure a production installation of OpenRemote with a your own certificate or automatically use one from Let's Encrypt.
Preserving data and configuration
docker-compose up execution stops the stack running in the foreground. The OpenRemote containers will stop but not be removed. To stop and remove the containers, use:
This will not affect your data, which is durably stored independently from containers in Docker volumes (see all with
docker volume ls):
openremote_deployment-data(map tiles, static resources)
openremote_postgresql-data(user/asset database storage)
openremote_proxy-data(SSL proxy configuration and certificates)
If you want to create a backup of your installation, make a copy of these volumes.
The default configuration will wipe the user/asset database storage and import demo data when containers are started! This can be changed with the environment variable
SETUP_WIPE_CLEAN_INSTALL. Set it to to
docker-compose.yml or provide it on the command line.
When a configuration environment variable is changed, you must recreate containers. Stop and remove them with
docker-compose down and then
docker-compose up the stack again.
More configuration options of the images are documented in the deploy.yml profile.
Contributing to OpenRemote
We work with Java, Groovy, TypeScript, Gradle, Docker, and a wide range of APIs and protocol implementations. Clone or checkout this project and send us pull requests, ensure that code is covered by tests and that the full test suite passes.
For more information and how to set up a development environment, see the Developer Guide.
Join us on the community forum.