Skip to content

Commit 463ebcc

Browse files
PRAteek-singHWYPRAteek-singHWY
authored
docs: add macOS local development setup guide (#658)
* docs: add macOS local development setup guide * docs(readme): restore original content and add macOS setup notes
1 parent 227ce51 commit 463ebcc

File tree

1 file changed

+222
-79
lines changed

1 file changed

+222
-79
lines changed

‎README.md‎

Lines changed: 222 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,126 +1,269 @@
1-
# OpenCRE readme
1+
# OpenCRE
22

3-
Go to https://www.opencre.org to see OpenCRE working and more explanation.
4-
OpenCRE stands for Open Common Requirement enumeration. It is an interactive content linking platform for uniting security standards and guidelines. It offers easy and robust access to relevant information when designing, developing, testing and procuring secure software.
3+
Go to [https://www.opencre.org](https://www.opencre.org) to see OpenCRE working and more explanation.
4+
OpenCRE stands for Open Common Requirement enumeration. It is an interactive content linking platform for uniting security standards and guidelines. It offers easy and robust access to relevant information when designing, developing, testing and procuring secure software.
55

66
OpenCRE consists of:
7-
- The application: a python web and cli application to access the data, running publicly at opencre.org
8-
- The catalog data: a catalog of Common Requirements (CREs)
9-
- The mapping data: links from each CRE to relevant sections in a range of standards
10-
- Tools and guidelines to contribute to the data and to run the application locally
7+
8+
* The application: a python web and cli application to access the data, running publicly at opencre.org
9+
* The catalog data: a catalog of Common Requirements (CREs)
10+
* The mapping data: links from each CRE to relevant sections in a range of standards
11+
* Tools and guidelines to contribute to the data and to run the application locally
1112

1213
# Contribute code or mappings
13-
To see how you can contribute to the application or to the data (catalog or standard mappings), see [Contributing](docs/CONTRIBUTING.md).
14+
15+
To see how you can contribute to the application or to the data (catalog or standard mappings), see [Contributing](docs/CONTRIBUTING.md).
1416
We really welcome you!
1517

1618
# Roadmap
19+
1720
For a roadmap please see the [issues](https://github.com/OWASP/OpenCRE/issues).
1821

1922
# Running your own OpenCRE
2023

2124
You are free to use the public opencre application at opencre.org. Apart from that, you can run your own if you want to include your own security standards and guidelines for example. We call that myOpenCRE.
2225

23-
### Locally
26+
## Locally
27+
28+
### Docker
2429

25-
#### Docker
2630
The easiest way to run OpenCRE locally is by running the published docker container.
2731
You can do so by running:
28-
`docker run -p 5000:5000 ghcr.io/owasp/opencre/opencre:latest`
29-
After the container has finished downloading the remote information you can access it in [localhost](http://127.0.0.1:5000)
30-
If you want to develop on OpenCRE or docker is not available in your environment, you can alternatively run it via CLI
3132

32-
#### Command Line
33+
```bash
34+
docker run -p 5000:5000 ghcr.io/owasp/opencre/opencre:latest
35+
```
36+
37+
After the container has finished downloading the remote information you can access it in [http://127.0.0.1:5000](http://127.0.0.1:5000).
38+
39+
If you want to develop on OpenCRE or docker is not available in your environment, you can alternatively run it via CLI.
40+
41+
### Command Line
3342

3443
To run outside of Docker you need to install OpenCRE.
3544
To install this application you need python3, yarn and virtualenv.
36-
* Clone the repository:
37-
<pre>git clone https://github.com/OWASP/common-requirement-enumeration </pre>
3845

39-
* (Recommend) Create and activate a Python virtual environment:
40-
<pre>python3 -m venv venv
41-
source venv/bin/activate </pre>
46+
Clone the repository:
47+
48+
```bash
49+
git clone https://github.com/OWASP/common-requirement-enumeration
50+
```
51+
52+
(Recommended) Create and activate a Python virtual environment:
53+
54+
```bash
55+
python3 -m venv venv
56+
source venv/bin/activate
57+
```
58+
59+
Install dependencies:
60+
61+
```bash
62+
make install
63+
```
64+
65+
Download the latest CRE graph from upstream by running:
66+
67+
```bash
68+
make upstream-sync
69+
```
70+
71+
Keep in mind that until [Issue #534](https://github.com/OWASP/OpenCRE/issues/534) is fixed you won't have access to gap analysis results locally.
72+
73+
To run CRE locally then you can do:
74+
75+
```bash
76+
make dev-flask
77+
```
78+
79+
To run the CLI application, you can run:
80+
81+
```bash
82+
python cre.py --help
83+
```
84+
85+
To download a remote CRE spreadsheet locally you can run:
86+
87+
```bash
88+
python cre.py --review --from_spreadsheet <google sheets url>
89+
```
90+
91+
To add a remote spreadsheet to your local database you can run:
92+
93+
```bash
94+
python cre.py --add --from_spreadsheet <google sheets url>
95+
```
96+
97+
To run the web application for development you can run:
98+
99+
```bash
100+
make start-containers
101+
make start-worker
102+
103+
# in a separate shell
104+
make dev-flask
105+
```
106+
107+
Alternatively, you can use the dockerfile with:
108+
109+
```bash
110+
make docker && make docker-run
111+
```
112+
113+
Some features like Gap Analysis require a neo4j DB running, you can start this with:
114+
115+
```bash
116+
make docker-neo4j
117+
```
118+
119+
Environment variables for app to connect to neo4jDB (default):
120+
121+
* `NEO4J_URL` (neo4j//neo4j:password@localhost:7687)
122+
123+
To run the web application for production you need gunicorn and you can run from within the cre_sync dir:
42124

43-
* Install dependencies
44-
<pre> make install </pre>
125+
```bash
126+
make prod-run
127+
```
128+
129+
---
130+
131+
### macOS Notes (Apple Silicon & Intel)
132+
133+
OpenCRE is fully supported on macOS. The following notes are optional and intended to help contributors running OpenCRE locally on macOS systems.
134+
135+
#### Prerequisites
136+
137+
Install required tools using Homebrew:
45138

46-
* Download the latest CRE graph from upstream by running
47-
<pre>make upstream-sync </pre>
48-
Keep in mind that until [Issue #534](https://github.com/OWASP/OpenCRE/issues/534) is fixed you won't have access to gap analysis results locally
139+
```bash
140+
brew install python@3.11 yarn make
141+
```
49142

50-
* To run CRE locally then you can do:
51-
<pre> make dev-flask </pre>
143+
> Note: Python 3.11 is recommended. Newer Python versions may cause dependency incompatibilities.
52144
53-
To run the CLI application, you can run
54-
<pre>python cre.py --help</pre>
145+
Verify Python version:
55146

56-
To download a remote cre spreadsheet locally you can run
57-
<pre>python cre.py --review --from_spreadsheet < google sheets url></pre>
147+
```bash
148+
python3 --version
149+
```
58150

59-
To add a remote spreadsheet to your local database you can run
60-
<pre>python cre.py --add --from_spreadsheet < google sheets url></pre>
151+
#### Virtual Environment Setup
61152

62-
To run the web application for development you can run
63-
<pre>
64-
$ make start-containers
65-
$ make start-worker
153+
Create and activate a virtual environment explicitly using Python 3:
66154

67-
# in a seperate shell
68-
$ make dev-flask
69-
</pre>
155+
```bash
156+
python3 -m venv venv
157+
source venv/bin/activate
158+
```
70159

71-
Alternatively, you can use the dockerfile with
72-
<pre>make docker && make docker-run</pre>
160+
Upgrade pip:
73161

74-
Some features like Gap Analysis require a neo4j DB running, you can start this with
75-
<pre>make docker-neo4j</pre>
76-
enviroment varaibles for app to connect to neo4jDB (default):
77-
- NEO4J_URL (neo4j//neo4j:password@localhost:7687)
162+
```bash
163+
pip install --upgrade pip
164+
```
78165

79-
To run the web application for production you need gunicorn and you can run from within the cre_sync dir
80-
<pre>make prod-run</pre>
166+
#### Dependency Installation
81167

168+
Install dependencies using the standard workflow:
82169

83-
### Using the OpenCRE API
84-
See [the myOpenCRE user guide](docs/my-opencre-user-guide.md) on using the OpenCRE API to for example add your own security guidelines and standards.
170+
```bash
171+
make install
172+
```
85173

174+
If you encounter build issues, ensure Xcode Command Line Tools are installed:
175+
176+
```bash
177+
xcode-select --install
178+
```
179+
180+
#### Running Locally
181+
182+
Sync upstream CRE data (requires internet access):
183+
184+
```bash
185+
make upstream-sync
186+
```
187+
188+
Then start the local server:
189+
190+
```bash
191+
make dev-flask
192+
```
193+
194+
The application will be available at:
195+
196+
```
197+
http://127.0.0.1:5000
198+
```
199+
200+
> Tip: For most macOS users, running via Docker is the simplest and most reliable approach.
201+
202+
---
203+
204+
## Using the OpenCRE API
205+
206+
See [the myOpenCRE user guide](docs/my-opencre-user-guide.md) on using the OpenCRE API to, for example, add your own security guidelines and standards.
207+
208+
## Docker building and running
209+
210+
You can build the production or the development docker images with:
211+
212+
```bash
213+
make docker-prod
214+
make docker-dev
215+
```
86216

87-
### Docker building and running
88-
You can build the production or the development docker images with
89-
`make docker-prod` and `make docker-dev` respectively
90217
The environment variables used by OpenCRE are:
218+
219+
```
220+
- NEO4J_URL
221+
- NO_GEN_EMBEDDINGS
222+
- FLASK_CONFIG
223+
- DEV_DATABASE_URL
224+
- INSECURE_REQUESTS
225+
- REDIS_HOST
226+
- REDIS_PORT
227+
- REDIS_NO_SSL
228+
- REDIS_URL
229+
- GCP_NATIVE
230+
- GOOGLE_SECRET_JSON
231+
- GOOGLE_CLIENT_ID
232+
- GOOGLE_CLIENT_SECRET
233+
- LOGIN_ALLOWED_DOMAINS
234+
- OpenCRE_gspread_Auth
91235
```
92-
- name: NEO4J_URL
93-
- name: NO_GEN_EMBEDDINGS
94-
- name: FLASK_CONFIG
95-
- name: DEV_DATABASE_URL
96-
- name: INSECURE_REQUESTS # development or TLS terminated environments only
97-
- name: REDIS_HOST
98-
- name: REDIS_PORT
99-
- name: REDIS_NO_SSL
100-
- name: REDIS_URL # in case REDIS_HOST and REDIS_PORT are unavailable
101-
- name: GCP_NATIVE # if there are ambient GCP credentials, only useful for VERTEX chatbot
102-
- name: GOOGLE_SECRET_JSON # if not running on GCP
103-
- name: GOOGLE_CLIENT_ID # useful for login only
104-
- name: GOOGLE_CLIENT_SECRET # useful for login only
105-
- name: LOGIN_ALLOWED_DOMAINS # useful for login only
106-
- name: OpenCRE_gspread_Auth # useful only when importing data, possible values 'oauth' or 'service_account'
107-
```
108-
You can run the containers with `make docker-prod-run` and `make-docker-dev-run`
109-
110-
### Developing
111-
112-
You can run backend tests with
113-
<pre>make test</pre>
114-
You can run get a coverage report with
115-
<pre>make cover</pre>
116-
Try to keep the coverage above 70%
117236

237+
You can run the containers with:
238+
239+
```bash
240+
make docker-prod-run
241+
make docker-dev-run
242+
```
243+
244+
## Developing
245+
246+
You can run backend tests with:
247+
248+
```bash
249+
make test
250+
```
251+
252+
You can get a coverage report with:
253+
254+
```bash
255+
make cover
256+
```
257+
258+
Try to keep the coverage above 70%.
259+
260+
---
118261

119262
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
120263
[![GitHub Super-Linter](https://github.com/OWASP/common-requirement-enumeration/workflows/Lint%20Code%20Base/badge.svg)](https://github.com/marketplace/actions/super-linter)
121-
[![Main Branch Build](https://github.com/OWASP/common-requirement-enumeration/workflows/Test/badge.svg?branch=main)](https://github.com/OWASP/OWASP/common-requirement-enumeration/workflows/Test)
264+
[![Main Branch Build](https://github.com/OWASP/common-requirement-enumeration/workflows/Test/badge.svg?branch=main)](https://github.com/OWASP/common-requirement-enumeration/workflows/Test)
122265

123-
[![Issues](https://img.shields.io/github/issues/owasp/common-requirement-enumeration)](https://github.com/OWASP/common-requirement-enumeration/issues)
266+
[![Issues](https://img.shields.io/github/issues/owasp/common-requirement-enumeration)](https://github.com/OWASP/common-requirement-enumeration/issues)
124267
[![PR's Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat)](http://makeapullrequest.com)
125268
![GitHub contributors](https://img.shields.io/github/contributors/owasp/common-requirement-enumeration)
126269
![GitHub last commit](https://img.shields.io/github/last-commit/owasp/common-requirement-enumeration)

0 commit comments

Comments
 (0)