You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+42-27Lines changed: 42 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,9 @@ Can scaffold and maintain your cloud solution on top of Cloudharness without wri
7
7
Kubernetes templates, with in place common utilities and applications already configured for you.
8
8
9
9
What building your cloud solution with CloudHarness gives to you:
10
+
10
11
- Common framework and utilities to develop and deploy micro-service application
12
+
11
13
- Helm chart automatic generation
12
14
- deployments
13
15
- services
@@ -23,11 +25,13 @@ What building your cloud solution with CloudHarness gives to you:
23
25
- databases (postgreql)
24
26
- access gatekeepers configuration
25
27
- secrets and configmaps
28
+
26
29
* Automatic build and push of images
27
30
* REST-API scaffolding building based on OpenApi
28
31
* Continuous deployment script generation
29
32
* Debug backend applications running on Kubernetes
30
33
* Python cluster access utilities
34
+
31
35
* Prebuilt support applications and shared library to:
32
36
* Log in and user management - based on Keycloak
33
37
* Submit batch and asynchronous workflows - based on Argo
@@ -43,17 +47,18 @@ What building your cloud solution with CloudHarness gives to you:
43
47
44
48
The microservice architecture is a great to get code separation and flexible development, but may not be of easy implementation, especially for small development teams/projects.
45
49
In particular, these questions may rise:
46
-
- How do I create a deployment for my microservices?
47
-
- How do I orchestrate my microservices?
48
-
- How to create consistent api documentation?
49
-
- Do I need to be an experienced devops to create a micro-service based application?
50
-
- Wouldn't it be nice to develop a plain database/backend/frontend application without infrastructure boilerplate but still be able to configure everything I want when needed?
51
-
- How to run batch operations like ETL processes easily and efficiently in a cloud environment?
52
-
- How to manage databases without being locked to a specific vendor solution?
53
-
- How to perform database backups?
54
-
- How to manage secret data?
55
-
- What about having a precounfigured account management application?
56
-
- Sooner rather than later I'll need an orchestration queue. Why not have that just ready to use?
50
+
51
+
- How do I create a deployment for my microservices?
52
+
- How do I orchestrate my microservices?
53
+
- How to create consistent api documentation?
54
+
- Do I need to be an experienced devops to create a micro-service based application?
55
+
- Wouldn't it be nice to develop a plain database/backend/frontend application without infrastructure boilerplate but still be able to configure everything I want when needed?
56
+
- How to run batch operations like ETL processes easily and efficiently in a cloud environment?
57
+
- How to manage databases without being locked to a specific vendor solution?
58
+
- How to perform database backups?
59
+
- How to manage secret data?
60
+
- What about having a precounfigured account management application?
61
+
- Sooner rather than later I'll need an orchestration queue. Why not have that just ready to use?
57
62
58
63
# Command line tools
59
64
@@ -63,30 +68,34 @@ CloudHarness provides the following command line tools to help application scaff
63
68
*`harness-application` - create a new CloudHarness REST application.
64
69
*`harness-generate` - generates server and client code for all CloudHarness REST applications.
65
70
*`harness-test` - run end to end tests
66
-
71
+
67
72
# Get started
68
73
69
74
## Prerequisites
70
75
71
76
### Operative system
72
77
73
78
Cloudharness can be used on all major operative systems.
79
+
74
80
- Linux: supported and tested
75
81
- MacOS: supported and tested
76
82
- Windows/WSL2: supported and tested
77
83
- Windows native: mostly working, unsupported
78
84
79
85
### Python
80
-
Python 3.9 must be installed.
86
+
87
+
Python 3.10+ must be installed.
81
88
82
89
It is recommended to setup a virtual environment.
83
90
With conda:
91
+
84
92
```bash
85
93
conda create --name ch python=3.12
86
94
conda activate ch
87
95
```
88
96
89
97
### Docker
98
+
90
99
[Docker](https://www.docker.com) is required to build locally.
91
100
92
101
### Kubernetes command line client
@@ -110,6 +119,7 @@ conda activate ch
110
119
A node environment with npm is required for developing web applications and to run end to end tests.
111
120
112
121
Recommended:
122
+
113
123
- node >= v14.0.0
114
124
- npm >= 8.0.0
115
125
@@ -120,26 +130,31 @@ A JRE is needed to run the code generators based on openapi-generator.
120
130
For more info, see [here](https://openapi-generator.tech/docs/installation).
121
131
122
132
## CloudHarness command line tools
133
+
123
134
To use the cli tools, install requirements first:
124
135
125
136
```bash
126
137
bash install.sh
127
138
```
128
-
### Generate deployment
129
139
130
-
To generate a deployment, run `harness-deployment`. See [below](#Deployment) for more.
140
+
### Create a new REST application
131
141
132
-
### Create new REST application
133
-
To create a new REST application, run `harness-application` from the root of your solution.
142
+
`harness-application` is a command-line tool used to create new applications based on predefined code templates. It allows users to quickly scaffold applications with backend, frontend, and database configurations.
143
+
More information can be found [here](./docs/applications/harness-application.md).
134
144
135
145
### Generate server and client code from openapi
136
-
To (re)generate the code for your applications, run `harness-generate` from the root.
137
-
The script will look for all openapi applications, and regenerate the Flask server code and documentation.
138
-
Note: the script will eventually override any manually modified file. To avoid that, define a file openapi-generator-ignore.
146
+
147
+
To (re)generate the code for your applications, run `harness-generate`.
148
+
`harness-generate` is a command-line tool used to generate client code, server stubs, and model libraries for applications.
149
+
More information can be found [here](./docs/applications/harness-generate.md)
150
+
151
+
### Generate deployment
152
+
153
+
To generate a deployment, run `harness-deployment`. See [below](#build-and-deploy) for more information.
139
154
140
155
# Extend CloudHarness to build your project
141
156
142
-
CloudHarness is born to be extended.
157
+
CloudHarness is born to be extended.
143
158
144
159
The quickest way to start is to install Cloud Harness, copy the *blueprint* folder and build from that with the cli tools, such as
# Use harness-application to create a new application from templates
1
+
# Use harness-application to create a new application
2
2
3
-
## Choosing Templates
3
+
## Overview
4
4
5
-
If you create a new application, you can choose templates that are used to generate the application scaffold.
5
+
`harness-application` is a command-line tool used to create new applications from predefined code templates. It allows users to quickly scaffold applications with backend, frontend, and database configurations.
6
6
7
-
Running `harness-application --help` will list the currently available templates:
7
+
## Usage
8
8
9
+
```sh
10
+
harness-application [name] [-t TEMPLATE]
9
11
```
10
-
usage: harness-application [-h] [-t TEMPLATES] name
11
12
12
-
Creates a new Application.
13
+
## Arguments
14
+
15
+
-`name`*(required)* – The name of the application to be created.
16
+
17
+
## Options
18
+
19
+
-`-h, --help` – Displays the help message and exits.
20
+
-`-t TEMPLATES, --template TEMPLATES` – Specifies one or more templates to use when creating the application.
21
+
22
+
## Choosing Templates
13
23
14
-
positional arguments:
15
-
name Application name
24
+
When creating a new application, you can choose templates that define its structure and components. Running `harness-application --help` will list the currently available templates:
16
25
17
-
optional arguments:
18
-
-h, --help show this help message and exit
19
-
-t TEMPLATES, --template TEMPLATES
20
-
Add a template name. Available templates: - base (always included) - flask-server (backend flask app based on openapi) - webapp (webapp including backend and frontend) - db-postgres - db-neo4j - db-mongo - django-app (fastapi django backend based on openapi)
26
+
```sh
27
+
usage: harness-application [-h] [-t TEMPLATES] name
21
28
```
22
29
23
30
## Available Templates
24
31
25
32
### Base
26
33
27
-
* The `base` template is always included and used as foundation for any other template.
34
+
- The `base` template is always included and serves as the foundation for any other template.
35
+
36
+
### Backend Templates
37
+
38
+
#### Flask Server
39
+
40
+
- The `flask-server` template consists of a backend built using [Flask](https://flask.palletsprojects.com/en/1.1.x/).
41
+
- Uses [Connexion](https://github.com/zalando/connexion) to map OpenAPI definitions to Flask routes.
42
+
- Served by [Gunicorn](https://gunicorn.org/) with 2 synchronous workers by default.
43
+
- Supports customization of the worker count and type.
44
+
45
+
#### Django
46
+
47
+
- The `django-fastapi` consists of a backend based on [FastAPI](https://fastapi.tiangolo.com/) and [Django](https://www.djangoproject.com/).
48
+
- Uses the [FastAPI code generator](https://github.com/koxudaxi/fastapi-code-generator) to map OpenAPI definitions.
49
+
- Served by [Uvicorn](https://www.uvicorn.org/) with 2 workers by default.
50
+
- The `django-ninja` consists of a backend based on [Django Ninja](https://django-ninja.dev/)
51
+
- Provides automatic OpenAPI schema generation.
52
+
- Supports Django's built-in ORM for seamless database integration.
53
+
- High performance due to Pydantic-based data validation.
54
+
- Simplifies request parsing and authentication.
28
55
29
-
### Flask Server
30
-
* It consists of a single backend, a Python [Flask](https://flask.palletsprojects.com/en/1.1.x/) application.
31
-
* The [Connexion](https://github.com/zalando/connexion) library maps the OpenAPI definition to Flask routing.
32
-
* Per default, [Gunicorn](https://gunicorn.org/) serves the Flask app with 2 synchronous workers. Depending on the application requirements, you can update the number of workers or choose a different [worker type](https://docs.gunicorn.org/en/stable/design.html).
56
+
### Full-Stack Templates
33
57
58
+
#### Webapp
34
59
35
-
### Webapp
60
+
- The `webapp` template extends the `base` template by adding a [React](https://reactjs.org/) frontend.
61
+
- The frontend bundle is served by the Python backend.
62
+
- React is used by default, but other frontend technologies can be integrated.
36
63
37
-
* The `webapp` template consists builds upon the `base` template extends it by a [React](https://reactjs.org/) frontend application.
38
-
* The generated frontend bundle is served by the Python backend.
39
-
* Per default, React is used as a frontend application, but you are free to choose a different frontend technology.
64
+
### Database Templates
40
65
66
+
-`db-postgres` – [PostgreSQL](https://www.postgresql.org/), a relational database.
67
+
-`db-neo4j` – [Neo4J](https://neo4j.com/), a graph database.
68
+
-`db-mongo` – [MongoDB](https://www.mongodb.com/), a NoSQL document-based database.
41
69
42
-
### Databases
70
+
## Examples
71
+
72
+
### Create a New Flask-Based Microservice Application
73
+
74
+
```sh
75
+
harness-application myapp
76
+
```
77
+
78
+
### Create a Full-Stack Web Application
79
+
80
+
```sh
81
+
harness-application myapp -t webapp
82
+
```
83
+
84
+
### Create a Web Application with a Mongo Database
85
+
86
+
```sh
87
+
harness-application myapp -t webapp -t db-mongo
88
+
```
89
+
90
+
### Display Help Information
91
+
92
+
```sh
93
+
harness-application --help
94
+
```
43
95
44
-
Additionally, you can choose one of the following database templates:
45
-
*`db-postgres` - [PostgreSQL](https://www.postgresql.org/), a relational database
46
-
*`db-neo4j`- [Neo4J](https://neo4j.com/), a graph database
47
-
*`db-mongo` - [MongoDB](https://www.mongodb.com/), a NoSQL document-based database
96
+
## Notes
48
97
49
-
### Django
50
-
* It consists of a single backend, a Python [FastAPI](https://fastapi.tiangolo.com/) application.
51
-
* The [FastAPI code generator](https://github.com/koxudaxi/fastapi-code-generator) maps the OpenAPI definition to FastAPI routing.
52
-
* The [Django framework](https://www.djangoproject.com/) encourages rapid development and clean, pragmatic design.
53
-
* Per default, [Uvicorn](https://www.uvicorn.org/) serves the FastAPI app with 2 workers. Depending on the application requirements, you can update the number of workers.
98
+
- Multiple templates can be specified by concatenating the `-t` parameter.
99
+
- The tool generates the necessary scaffolding for the chosen templates.
100
+
- Ensure you have the required dependencies installed before running the generated application.
101
+
- For more information, run `harness-application --help` or check out the additional documentation:
# Use harness-generate to generate server and client stubs
2
+
3
+
To (re)generate the code for your applications, run `harness-generate`.
4
+
`harness-generate` is a command-line tool used to generate client code, server stubs, and model libraries for applications. It walks through the filesystem inside the `./applications` folder to create and update application scaffolding. The tool supports different generation modes and allows for both interactive and non-interactive usage.
0 commit comments