Skip to content

Commit 66ed842

Browse files
vDonGlovervDonGlover
authored
Add a readme for the SDK (#1008)
* Initial SDK readme * update server description. * Address PR feedback * Address additional PR feedback * Address PR feedback * Additional PR feedback updates. * Further feedback updates * PR feedback updates
1 parent 67b393c commit 66ed842

File tree

1 file changed

+133
-0
lines changed

1 file changed

+133
-0
lines changed

‎production/sdk/README.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Getting Started with the Gaia SDK
2+
3+
This document provides guidance on setting up the Gaia SDK, which includes the Gaia Database Server.
4+
5+
## Prerequisites
6+
7+
Before you begin, make sure that you have the following prerequisites:
8+
9+
- Ubuntu Linux 20.04
10+
- A machine that supports the x64 architecture.
11+
12+
The Gaia SDK installer installs the Gaia tools and Clang 10.
13+
14+
CMake is the officially supported method for building Gaia applications. In addition, the Gaia SDK uses CMake to automate code generation from DDL and ruleset files.
15+
16+
To install CMake, run the following command:
17+
18+
```bash
19+
sudo apt-get install cmake
20+
```
21+
22+
To build Gaia exmamples using CMake and make tools, specify the Clang compiler by setting the following variables in your environment:
23+
24+
```bash
25+
export CC=/usr/bin/clang-10
26+
export CPP=/usr/bin/clang-cpp-10
27+
export CXX=/usr/bin/clang++-10
28+
export LDFLAGS="-B/usr/lib/llvm-10/bin/ -fuse-ld=lld"
29+
```
30+
31+
## Download the Gaia SDK
32+
33+
The Gaia SDK is delivered as a Debian software package (DEB):
34+
35+
gaia-x.y.z_amd64.deb
36+
37+
Where x.y.z represents the Gaia version number.
38+
39+
The Gaia SDK includes the Database Server executable and the Gaia Declarative C++ SDK.
40+
41+
To download the package, use the URL that you were sent in your welcome email.
42+
43+
## Install the package
44+
45+
You must have sudo privileges to install the package.
46+
47+
To install the package:
48+
49+
1. Navigate to the folder that contains the downloaded package.
50+
2. At the command prompt, replace the x.y.z with the correct version number and run the following commands:
51+
52+
```bash
53+
sudo apt-get update
54+
sudo apt-get install ./gaia-x.y.z_amd64.deb
55+
```
56+
57+
To remove the package:
58+
59+
1. At the command prompt, run the following command:
60+
61+
```bash
62+
sudo apt-get remove gaia
63+
```
64+
65+
To update the package, remove it and install the updated package:
66+
67+
1. Download the updated package.
68+
2. Remove the currently installed package, run the following command:
69+
70+
```bash
71+
sudo apt-get remove gaia
72+
```
73+
3. Navigate to the folder that contains the updated package.
74+
4. After replacing the x.y.z with the version number of the package that you are installing, run the following command:
75+
76+
```bash
77+
sudo apt-get install ./gaia-x.y.z_amd64.deb
78+
```
79+
80+
### Installed components
81+
82+
<pre>
83+
/opt/gaia/bin
84+
gaia_db_server - The Gaia Database Server.
85+
gaiac - Gaia Catalog Tool.
86+
gaiat - Gaia Translation Engine.
87+
/opt/gaia/etc
88+
gaia.conf - Contains configuration settings for the platform and application loggers that the Gaia Platform uses.
89+
gaia_log.conf - Contains configuration settings for the Database Server and rules engine that comprise the Gaia Platform.
90+
/opt/gaia/examples/
91+
Example apps.
92+
/opt/gaia/include
93+
Include files for the Gaia Platform.
94+
/opt/gaia/lib
95+
Library files for the Gaia Platform.
96+
</pre>
97+
98+
## Start the Gaia server
99+
100+
To build or run any solution that is based on the Gaia Platform, the Gaia server must be running .
101+
102+
We recommend that you don't run gaia\_db\_server under the root user. As with any daemon process that is accessible to the outside, running the Database Server process as root, or any other account with special access rights, is a security risk. As best practice in production, run Gaia under a separate user account. This user account should only own the data that is managed by the server, and should not be used to run other daemons. For example, using the user `nobody` is not recommended.
103+
104+
To prevent a compromised server process from modifying the Gaia executables, the user account must not own the Gaia executable files.
105+
106+
Gaia server command line arguments:
107+
108+
| Option | Description |
109+
|---|---|
110+
| --persistence \<mode> | If not specified, the default mode is enabled.<br>The data location is specified with --data-dir.<br>- <enabled>: Persist data [default].<br>- <disabled>: Do not persist any data.<br>- <disabled-after-recovery>: Load data from the datastore and disable persistence. |
111+
| --data-dir \<database-folder-path> | Specifies the location in which to store the database. |
112+
| --configuration-file-path \<config-file-name> | Specifies the location in which to store the Gaia configuration file. |
113+
| --reinitialize-persistent-store | All previous changes to the database are deleted from persistent storage and will not be visible after the Database Server is started, Changes to the database made while the Database Server is running will be visible after it is restarted. |
114+
115+
To start the server on a machine that supports systemd:
116+
117+
```bash
118+
sudo systemctl start gaia
119+
```
120+
121+
### Starting the Gaia server on Windows Subsystem for Linux (WSL)
122+
123+
When starting the Gaia server on WSL, use the --data-dir argument to specify the location in which to store the database. We recommend that you store it locally in ~/.local/gaia/db.
124+
125+
To start the server on Ubuntu and run it in the background on WSL2 (Gaia has not been tested on WSL1):
126+
127+
```bash
128+
gaia_db_server --data-dir ~/.local/gaia/db &
129+
```
130+
131+
## Next Steps
132+
133+
[Gaia Technical Documentation](http://docs.gaiaplatform.io)

0 commit comments

Comments
 (0)