Add README markdown template for custom projects#59
Add README markdown template for custom projects#59MartinaeyNL wants to merge 11 commits intomainfrom
Conversation
… OpenRemote or open source users.
There was a problem hiding this comment.
Pull request overview
This PR transforms the README from basic documentation into a comprehensive template for custom OpenRemote projects. The template is designed to help teams document their custom project setup, architecture, development workflow, and deployment environments in a structured way.
Changes:
- Restructured README to be a fill-in template with extensive sections for project context, architecture, developer guide, and deployments
- Added placeholder sections for features, vocabulary, company background, and environment-specific deployment information
- Moved Docker Compose documentation into a dedicated Developer Guide section
- Removed some original content about setup tasks and encrypted files
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
|
The code review window can be quite unclear of what the new README will look like, |
|
I'm happy with the current state. 👍 Let's iterate on this, so I can process any proposed changes. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # OpenRemote Custom Project Template | ||
|
|
||
| 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. | ||
|
|
||
| ## Documentation | ||
| **[You can find the documentation here](https://docs.openremote.io/docs/user-guide/deploying/custom-deployment/)**. | ||
|
|
||
| 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. | ||
| <br /> | ||
|
|
||
| **[You can find the documentation here](https://docs.openremote.io/docs/user-guide/deploying/custom-deployment/)**. | ||
| --- | ||
|
|
||
| ## Docker Compose Files | ||
| # (PROJECT_NAME) | ||
|
|
There was a problem hiding this comment.
The README now contains two top-level headings (# OpenRemote Custom Project Template and # (PROJECT_NAME)). Since this file is intended to be copied/filled in for custom projects, having multiple H1s can confuse the document structure and TOC rendering. Consider keeping a single H1 (typically the project name) and demoting the template header to a smaller heading or an HTML comment/introduction section.
| ## Deployments / environments | ||
|
|
||
| Any other value will result in default setup. | ||
| 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 action. | ||
| <!-- If applicable, specify otherwise --> |
There was a problem hiding this comment.
This paragraph hard-codes assumptions that deployments are run by OpenRemote on managed infrastructure and via GitHub Actions. Because this README is meant as a general template for custom projects (including open-source users), the default text should be phrased as placeholders/options (e.g., self-managed vs OpenRemote-managed) rather than stating one specific operational model.
| ## Deployments / environments | ||
|
|
||
| Any other value will result in default setup. | ||
| 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 action. |
There was a problem hiding this comment.
Wording issue: "GitHub Actions CI/CD action" is confusing/incorrect terminology (GitHub Actions runs workflows; an "action" is a reusable step). Consider rephrasing to something like "GitHub Actions workflows" or "a GitHub Actions CI/CD pipeline" for clarity.
| 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 action. | |
| 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 GitHub Actions CI/CD workflows. |
| - **OpenRemote Manager:** https://(staging.CUSTOM_HOSTNAME).openremote.app/manager | ||
| - **Custom app:** https://(staging.CUSTOM_HOSTNAME).openremote.app/custom | ||
| <!-- If applicable, add additional URLs to other services or apps --> | ||
| ### `production` | ||
| Used for the live system with devices in the field, with guarantee of stability and data persistence. Important practices and agreements to be aware of: | ||
| - There is a daily backup active for this instance. | ||
| - This deployment is **manually updated**, and should be communicated with stakeholders. | ||
| <!-- 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" --> | ||
| - **OpenRemote Manager:** https://(CUSTOM_HOSTNAME).com/manager | ||
| - **Custom app:** https://(CUSTOM_HOSTNAME).com/custom |
There was a problem hiding this comment.
The example URLs use the OpenRemote-managed openremote.app domain and an example .com domain with placeholders in parentheses (which aren't valid in hostnames). For a template README, consider using consistently formatted placeholders like <STAGING_HOSTNAME> / <PRODUCTION_HOSTNAME> and avoid implying a specific domain/TLD unless that is a guaranteed convention for all users of this template.
| - **OpenRemote Manager:** https://(staging.CUSTOM_HOSTNAME).openremote.app/manager | |
| - **Custom app:** https://(staging.CUSTOM_HOSTNAME).openremote.app/custom | |
| <!-- If applicable, add additional URLs to other services or apps --> | |
| ### `production` | |
| Used for the live system with devices in the field, with guarantee of stability and data persistence. Important practices and agreements to be aware of: | |
| - There is a daily backup active for this instance. | |
| - This deployment is **manually updated**, and should be communicated with stakeholders. | |
| <!-- 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" --> | |
| - **OpenRemote Manager:** https://(CUSTOM_HOSTNAME).com/manager | |
| - **Custom app:** https://(CUSTOM_HOSTNAME).com/custom | |
| - **OpenRemote Manager:** https://<STAGING_HOSTNAME>/manager | |
| - **Custom app:** https://<STAGING_HOSTNAME>/custom | |
| <!-- If applicable, add additional URLs to other services or apps --> | |
| ### `production` | |
| Used for the live system with devices in the field, with guarantee of stability and data persistence. Important practices and agreements to be aware of: | |
| - There is a daily backup active for this instance. | |
| - This deployment is **manually updated**, and should be communicated with stakeholders. | |
| <!-- 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" --> | |
| - **OpenRemote Manager:** https://<PRODUCTION_HOSTNAME>/manager | |
| - **Custom app:** https://<PRODUCTION_HOSTNAME>/custom |
| <!-- For example; What systems are there, and how do they interact with each other. --> | ||
|
|
||
| ### Keycloak setup | ||
| 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. |
There was a problem hiding this comment.
In the Keycloak section, the repository is linked twice (the Keycloak name and then a second "[link]" pointing to the same URL). This reads redundant and doesn't add extra information; consider removing the duplicate link or linking the second reference to the specific default configuration file/directory you want readers to review.
| 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. | |
| The identity provider in place is [Keycloak](https://github.com/openremote/keycloak), running in its own container. The default configuration from the repository is used. |
1 participant
Description
This PR adds a
README.mdtemplate for custom projects to describe what their project is about.The main goal is to share enough information for all team members to be able to work and provide support in the project.
These changes would benefit repositories maintained by OpenRemote, and repositories created by open source users.
Fixes openremote/openremote#2365
Changelog
README.mdfile.