Skip to content

Commit e3b0d2c

Browse files
tomas-soltystomas-soltys
committed
C++20 is default and new deploy guide
1 parent 9756907 commit e3b0d2c

4 files changed

Lines changed: 306 additions & 3 deletions

File tree

‎DEPLOY_GUIDE.md‎

Lines changed: 303 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
1+
# Range Cloud Deployment Guide
2+
3+
## Overview
4+
5+
This guide describes how to deploy a Range Cloud instance:
6+
7+
| Name | Purpose |
8+
|------|---------|
9+
| Range Cloud | User files |
10+
11+
---
12+
13+
## Prerequisites
14+
15+
- Linux x86\_64 system
16+
- The Range Cloud package file: `range-cloud-<version>-linux-x86_64.tar.gz`
17+
- Write access to `$HOME` and to the directory where host SSL certificates will be stored
18+
- `tar` and `openssl` available on the system
19+
20+
---
21+
22+
## Configuration
23+
24+
The following values are used throughout this guide. Adjust them to match your environment before running any commands.
25+
26+
```bash
27+
# Your deployment
28+
HOST_NAME="your-host-name.com"
29+
ADMIN_ACCOUNT="admin.name@your-host-name.com"
30+
31+
# Directories
32+
CLOUD_DIR="$HOME/range-cloud"
33+
CA_DIR="$HOME/range-ca"
34+
35+
# Host SSL certificate paths (existing certificates from your CA/Let's Encrypt)
36+
HOST_PRIVATE_KEY="/etc/ssl/certs/${HOST_NAME}-privkey.pem"
37+
HOST_PUBLIC_KEY="/etc/ssl/certs/${HOST_NAME}-fullchain.pem"
38+
39+
# Certificate Authority identity details
40+
CA_COUNTRY="EU"
41+
CA_STATE="CZ"
42+
CA_LOCATION="Prague"
43+
CA_ORGANIZATION="Range Software"
44+
CA_ORG_UNIT="Cloud"
45+
CA_COMMON_NAME="$HOST_NAME"
46+
CA_EMAIL="tomas.soltys@${HOST_NAME}"
47+
48+
# Package file path
49+
PACKAGE_FILE="/path/to/range-cloud-<version>-linux-x86_64.tar.gz"
50+
```
51+
52+
---
53+
54+
## Directory and Port Layout
55+
56+
After deployment, the following directory structure is created:
57+
58+
```
59+
$HOME/
60+
├── range-ca/ # Certificate Authority
61+
└── range-cloud/ # Range Cloud instance
62+
├── bin/
63+
├── cert/
64+
│ └── clients/
65+
│ ├── root.key.pem
66+
│ └── root.cert.pem
67+
└── scripts/
68+
```
69+
70+
Network ports:
71+
72+
| Purpose | Port |
73+
|---------|------|
74+
| Public HTTP | `4080` |
75+
| Private HTTP (admin) | `4443` |
76+
77+
Ensure these ports are open in your firewall. The public port is used by clients; the private port is used for administration via `cloud-tool`.
78+
79+
---
80+
81+
## Step 1: Extract the Package
82+
83+
Extract the package to a temporary working directory. Keep `TMPDIR` and `PKGDIR` set for use in subsequent steps.
84+
85+
```bash
86+
TMPDIR=$(mktemp -d -t "RANGE-CLOUD.XXXXXXXXXX")
87+
PKGDIR="$TMPDIR/$(basename "$PACKAGE_FILE" .tar.gz)"
88+
89+
tar -xzvf "$PACKAGE_FILE" -C "$TMPDIR"
90+
```
91+
92+
> **Note:** `PKGDIR` is referenced in several later steps. Keep this shell session open or re-export the variable if you open a new terminal.
93+
94+
---
95+
96+
## Step 2: Set Up the Certificate Authority
97+
98+
The Range CA is a local certificate authority used to sign internal service certificates. It only needs to be created once. If `$CA_DIR` already exists, skip this step.
99+
100+
```bash
101+
if [ ! -d "$CA_DIR" ]; then
102+
"$PKGDIR/range-ca/scripts/ca_setup.sh" \
103+
--ca-dir="$CA_DIR" \
104+
--country="$CA_COUNTRY" \
105+
--state="$CA_STATE" \
106+
--location="$CA_LOCATION" \
107+
--organization="$CA_ORGANIZATION" \
108+
--organization-unit="$CA_ORG_UNIT" \
109+
--common-name="$CA_COMMON_NAME" \
110+
--email="$CA_EMAIL"
111+
fi
112+
```
113+
114+
---
115+
116+
## Step 3: Prepare Host SSL Certificates
117+
118+
The cloud instance requires a private key and a public certificate (full chain) for the host. Choose one of the two options below.
119+
120+
### Option A: Use Existing Certificates (Recommended)
121+
122+
If you already have valid SSL certificates for your domain (e.g., from Let's Encrypt), point the variables to those files:
123+
124+
```bash
125+
HOST_PRIVATE_KEY="/etc/ssl/certs/${HOST_NAME}-privkey.pem"
126+
HOST_PUBLIC_KEY="/etc/ssl/certs/${HOST_NAME}-fullchain.pem"
127+
```
128+
129+
Verify both files exist before proceeding:
130+
131+
```bash
132+
ls -la "$HOST_PRIVATE_KEY" "$HOST_PUBLIC_KEY"
133+
```
134+
135+
### Option B: Generate Self-Signed Certificates via the Range CA
136+
137+
Use this option if you do not have external certificates. The Range CA created in Step 2 is used to sign the host certificate.
138+
139+
```bash
140+
HOST_PRIVATE_KEY="$CLOUD_DIR/etc/ssl/certs/${HOST_NAME}-private.pem"
141+
HOST_PUBLIC_KEY="$CLOUD_DIR/etc/ssl/certs/${HOST_NAME}-public.pem"
142+
143+
mkdir -p "$(dirname "$HOST_PRIVATE_KEY")"
144+
mkdir -p "$(dirname "$HOST_PUBLIC_KEY")"
145+
146+
"$CA_DIR/scripts/ca_create_signed_certificate.sh" \
147+
--key="$HOST_PRIVATE_KEY" \
148+
--cert="$HOST_PUBLIC_KEY" \
149+
--extension="server_cert" \
150+
--country="$CA_COUNTRY" \
151+
--state="$CA_STATE" \
152+
--location="$CA_LOCATION" \
153+
--organization="$CA_ORGANIZATION" \
154+
--organization-unit="$CA_ORG_UNIT" \
155+
--common-name="$CA_COMMON_NAME" \
156+
--email="$CA_EMAIL"
157+
```
158+
159+
> The generated key and certificate files must not already exist. If they do, remove them first.
160+
161+
---
162+
163+
## Step 4: Deploy Range Cloud
164+
165+
Run the setup script. This creates and configures the service directory at `$CLOUD_DIR`.
166+
167+
```bash
168+
"$PKGDIR/scripts/cloud_setup.sh" \
169+
--cloud-directory="$CLOUD_DIR" \
170+
--range-ca="$CA_DIR" \
171+
--public-http-port=4021 \
172+
--private-http-port=4022 \
173+
--private-key="$HOST_PRIVATE_KEY" \
174+
--public-key="$HOST_PUBLIC_KEY" \
175+
--country="$CA_COUNTRY" \
176+
--state="$CA_STATE" \
177+
--location="$CA_LOCATION" \
178+
--organization="$CA_ORGANIZATION" \
179+
--organization-unit="$CA_ORG_UNIT" \
180+
--common-name="$CA_COMMON_NAME" \
181+
--email="$CA_EMAIL"
182+
```
183+
184+
---
185+
186+
## Step 5: Start the Service
187+
188+
```bash
189+
"$CLOUD_DIR/scripts/cloud_start.sh"
190+
```
191+
192+
---
193+
194+
## Step 6: Configure the Admin Account
195+
196+
After the service is running, create and configure the administrator account. The `cloud-tool` binary connects via the private HTTP port and authenticates using the root client certificates generated during setup.
197+
198+
```bash
199+
# Add the admin user
200+
"$CLOUD_DIR/bin/cloud-tool" \
201+
--http-port=4022 \
202+
--host-key="$HOST_PUBLIC_KEY" \
203+
--private-key="$CLOUD_DIR/cert/clients/root.key.pem" \
204+
--private-key-password="" \
205+
--public-key="$CLOUD_DIR/cert/clients/root.cert.pem" \
206+
--user-add \
207+
--resource-name="$ADMIN_ACCOUNT"
208+
209+
# Assign the admin user to the 'users' and 'root' groups
210+
"$CLOUD_DIR/bin/cloud-tool" \
211+
--http-port=4022 \
212+
--host-key="$HOST_PUBLIC_KEY" \
213+
--private-key="$CLOUD_DIR/cert/clients/root.key.pem" \
214+
--private-key-password="" \
215+
--public-key="$CLOUD_DIR/cert/clients/root.cert.pem" \
216+
--user-update \
217+
--resource-name="$ADMIN_ACCOUNT" \
218+
--json-content="{ \"name\": \"$ADMIN_ACCOUNT\", \"groups\": [ \"users\", \"root\" ] }"
219+
```
220+
221+
---
222+
223+
## Step 7: Clean Up Temporary Files
224+
225+
Remove the temporary extraction directory created in Step 1.
226+
227+
```bash
228+
rm -rf "$TMPDIR"
229+
```
230+
231+
---
232+
233+
## Verification
234+
235+
Check that the service is running and healthy:
236+
237+
```bash
238+
"$CLOUD_DIR/scripts/cloud_status.sh"
239+
```
240+
241+
---
242+
243+
## Ongoing Operations
244+
245+
All operational commands run directly against the deployed instance directory. No package file is required except for updates.
246+
247+
### Start the Service
248+
249+
```bash
250+
"$CLOUD_DIR/scripts/cloud_start.sh"
251+
```
252+
253+
### Stop the Service (Graceful)
254+
255+
```bash
256+
"$CLOUD_DIR/scripts/cloud_stop.sh"
257+
```
258+
259+
### Kill the Service (Force)
260+
261+
```bash
262+
"$CLOUD_DIR/scripts/cloud_stop.sh" --force
263+
```
264+
265+
### Check Service Status
266+
267+
```bash
268+
"$CLOUD_DIR/scripts/cloud_status.sh"
269+
```
270+
271+
### Update the Software
272+
273+
Updating stops the service, replaces the software, and restarts it. You need a new package file.
274+
275+
```bash
276+
# Re-extract the new package
277+
TMPDIR=$(mktemp -d -t "RANGE-CLOUD.XXXXXXXXXX")
278+
PKGDIR="$TMPDIR/$(basename "$PACKAGE_FILE" .tar.gz)"
279+
tar -xzvf "$PACKAGE_FILE" -C "$TMPDIR"
280+
281+
# Stop, update, and restart
282+
"$CLOUD_DIR/scripts/cloud_stop.sh"
283+
"$PKGDIR/scripts/cloud_update_software.sh" --cloud-directory="$CLOUD_DIR"
284+
"$CLOUD_DIR/scripts/cloud_start.sh"
285+
286+
# Clean up
287+
rm -rf "$TMPDIR"
288+
```
289+
290+
### Clear / Erase the Environment
291+
292+
> **Warning:** This permanently deletes all instance data. It cannot be undone.
293+
294+
```bash
295+
"$CLOUD_DIR/scripts/cloud_stop.sh"
296+
rm -rf "$CLOUD_DIR"
297+
```
298+
299+
To also remove the Certificate Authority:
300+
301+
```bash
302+
rm -rf "$CA_DIR"
303+
```

‎src/CMakeLists.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
cmake_minimum_required(VERSION 3.21)
22
project(RangeCloud)
33

4-
set(CMAKE_CXX_STANDARD 17)
4+
set(CMAKE_CXX_STANDARD 20)
55
set(CMAKE_CXX_STANDARD_REQUIRED ON)
66

77
include(Config.cmake)

‎src/range-base-lib‎

‎src/range-cloud-lib‎

0 commit comments

Comments
 (0)