Skip to content

Commit 33e3277

Browse files
MartinaeyNLMartinaeyNL
authored
Add README markdown template for custom projects (#59)
1 parent 2ea84c7 commit 33e3277

File tree

1 file changed

+97
-13
lines changed

1 file changed

+97
-13
lines changed

‎README.md‎

Lines changed: 97 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,113 @@
11
# OpenRemote Custom Project Template
22

3-
This repository is a template for custom projects; showing the recommended project structure and including `README` files in the `deployment` directory to provide details about how to customise each part.
3+
This repository is a template for custom projects; showing the recommended project structure and including `README` files in the `deployment` directory to provide details about how to customize each part.
44

5-
## Documentation
5+
**[You can find the documentation here](https://docs.openremote.io/docs/user-guide/deploying/custom-deployment/)**.
66

7-
The OpenRemote documentation contains more information about how to use this repository as a template to develop your own agents, services, model classes, setup tasks, tests, and new UI apps, including examples you could use as a starting point.
87

9-
**[You can find the documentation here](https://docs.openremote.io/docs/user-guide/deploying/custom-deployment/)**.
8+
---
9+
10+
# (PROJECT_NAME)
11+
12+
*(Please describe, in a short summary, the context of the project.)*
13+
<!-- For example:
14+
OpenRemote produces sensors for monitoring the power production of solar panels.
15+
They use ESP32 hardware that auto provisions in the OpenRemote platform through the cloud.
16+
This hardware gets delivered to end consumers in their homes, where they can use a dedicated app for monitoring their solar panels.
17+
-->
18+
19+
> This repository is set up using the [Custom Project template](https://github.com/openremote/custom-project/). This repository uses the same standards and folder structure. More information about how to use this repository as a template to develop your own agents, services, model classes, setup tasks, tests, and new UI apps can be found in the [OpenRemote documentation](https://docs.openremote.io/docs/developer-guide/creating-a-custom-project).
20+
<!-- If different from "normal custom projects", you can replace or add information here. For example, note additional folders, or source code outside this repository. -->
21+
22+
## Project context
23+
24+
### Features
25+
*(Please insert a bullet point list with features specific to this custom project.)*
26+
<!-- For example:
27+
- Custom app for end users to access their solar panel data.
28+
- Custom agent for communicating with the ESP32 devices.
29+
- Custom HAProxy configuration to add additional services managed by them.
30+
- Gateways ...
31+
- OR extensions in use ...
32+
-->
33+
34+
### Vocabulary / common terms
35+
*(Please insert a bullet point list with common terms in this project, with a short explanation.)*
36+
<!-- For example:
37+
- **Manager UI**: The end-user UI deployed on `https://<url>/manager/` for monitoring devices.
38+
-->
1039

11-
## Docker Compose Files
40+
### Company background
41+
*(If applicable, write context about the company this custom project is meant for.)*
42+
<!-- For example:
43+
- What kind of company they are (installer, manufacturer)
44+
- What kind of team we're working with
45+
- Whether they have an in-house development team
46+
- Who has access to this repository
47+
- If they write Groovy scripts yes/no
48+
- If they have their own outside repository, etc. -->
1249

13-
In the `profile` directory you can find different Docker compose files, each serving a different purpose. To be able to use them, you'll need to download a copy of the `deploy.yml` file from the main OpenRemote repository and place it in the `openremote/profile` directory, to ensure you always have the latest version of the file:
50+
## Architecture
51+
*(Please insert, preferably a diagram, or a short explanation of the high level architecture)*
52+
<!-- For example, what systems are there, and how do they interact with each other. -->
1453

54+
### Keycloak setup
55+
The identity provider in place is [Keycloak](https://github.com/openremote/keycloak), running in its own container. The default configuration from the repository ([link](https://github.com/openremote/keycloak)) is used.
56+
<!-- If the identity provider setup is different, or a custom configuration is used, please specify. -->
57+
58+
### Proxy setup
59+
All requests from and towards running services go through the [HAProxy](https://github.com/openremote/proxy) container. The default configuration from the repository ([haproxy.cfg](https://github.com/openremote/proxy/blob/main/haproxy.cfg)) is used.
60+
<!-- If the proxy setup is different, or a custom configuration is used, please specify. -->
61+
62+
<!-- Feel free to add additional chapters on architecture specific to this custom project -->
63+
64+
## Developer Guide
65+
66+
### Quickstart
67+
Before starting, make sure you have cloned the Git repository locally, as this is required.
68+
Follow the initial guides on the OpenRemote documentation on [preparing the environment](https://docs.openremote.io/docs/developer-guide/preparing-the-environment), [installing and using Docker](https://docs.openremote.io/docs/developer-guide/installing-and-using-docker), and on [setting up an IDE](https://docs.openremote.io/docs/developer-guide/setting-up-an-ide).
69+
70+
*(Please describe the steps necessary to run this custom project locally.)*
71+
72+
### Docker Compose files
73+
In the `profile` directory you can find different Docker Compose files, each serving a different purpose. To be able to use them, you'll need to download a copy of the `deploy.yml` file from the main OpenRemote repository and place it in the `openremote/profile` directory, to ensure you always have the latest version of the file:
1574
```bash
1675
mkdir -p openremote/profile && curl -L https://github.com/openremote/openremote/raw/refs/heads/master/profile/deploy.yml -o openremote/profile/deploy.yml
1776
```
1877

78+
### Environment variables
79+
80+
| Key | Containers | Description | Default |
81+
|----------------------|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------|----------|
82+
| `OR_HOSTNAME` | All services | **(REQUIRED)** FQDN hostname of where this instance will be exposed (localhost, IP address or public domain) | - |
83+
| `OR_ADMIN_PASSWORD` | `keycloak`, `manager` | **(REQUIRED)** Initial admin user password | - |
84+
| `DEPLOYMENT_VERSION` | `deployment` | **(REQUIRED)** The custom project version in use. This tag is used for building and deploying the artifacts from this repository. | - |
85+
| `MANAGER_VERSION` | `manager` | The OpenRemote version in use. | 'latest' |
86+
| `KEYCLOAK_VERSION` | `keycloak` | The Keycloak version in use. | 'latest' |
87+
| `PROXY_VERSION` | `proxy` | The HAProxy version in use. | 'latest' |
1988

20-
## Setup Tasks
21-
The following `OR_SETUP_TYPE` value(s) are supported:
89+
A list of all environment variables from OpenRemote can be found [here](https://github.com/openremote/openremote/blob/master/profile/deploy.yml).
90+
<!-- Feel free to add additional chapters on developer information such as local gateway setup, encrypted files in the repository, etc. -->
2291

23-
* `production` - Requires `CUSTOM_USER_PASSWORD` environment variable to be specified
92+
## Deployments / environments
2493

25-
Any other value will result in default setup.
94+
This custom project is deployed by OpenRemote on their managed infrastructure. It's running in Docker containers, using the `docker-compose.yml` file in the root folder of the repository. All deployments are run using the GitHub Actions CI/CD workflow.
95+
<!-- If applicable, specify otherwise -->
2696

27-
## Encrypted files
28-
If any encrypted files are added to the project then you will need to specify the `GFE_PASSWORD` environment variable to be able to build the project and decrypt the
29-
files.
97+
The list of available environments:
98+
### `staging`
99+
Used by OpenRemote to test new functionality and bugfixes before publishing them to production. Important practices and agreements to be aware of:
100+
- This environment is only used for development purposes, so can be offline at any time.
101+
- There is no guarantee that this data will be persisted in the long-term.
102+
<!-- If applicable, you can provide additional practices such as "Devices in the field are connected to this" or "Be aware that an external company has API access" -->
103+
- **OpenRemote Manager:** https://(staging.CUSTOM_HOSTNAME).com/manager
104+
- **Custom app:** https://(staging.CUSTOM_HOSTNAME).com/custom
105+
<!-- If applicable, add additional URLs to other services or apps -->
106+
### `production`
107+
Used for the live system with devices in the field, with a guarantee of stability and data persistence. Important practices and agreements to be aware of:
108+
- There is a daily backup active for this instance.
109+
- This deployment is **manually updated**, and should be communicated with stakeholders.
110+
<!-- If applicable, you can provide additional practices, such as "Auto deploys when making a new release through GitHub", or "It updates every 1st day of the month" -->
111+
- **OpenRemote Manager:** https://(CUSTOM_HOSTNAME).com/manager
112+
- **Custom app:** https://(CUSTOM_HOSTNAME).com/custom
113+
<!-- If applicable, add additional URLs to other services or apps -->

0 commit comments

Comments
 (0)