README_SETUP.md 4.27 KB
Newer Older
1
2
# Getting Started #

Henrik tom Wörden's avatar
Henrik tom Wörden committed
3
4
5
6
7
8
9
10
11
12
13
14
## Requirements ##
We use docker and docker-compose to deploy CaosDB:
- Docker >= 18.02
- docker-compose >= 1.21

On a Debian system, you can install the requirements with:

```sh
sudo apt-get install docker.io docker-compose
```

Note, that your user account needs to be in the docker group to start a
15
container. Security note: The docker group is equivalent to root permissions.
Henrik tom Wörden's avatar
Henrik tom Wörden committed
16
17
18
19

```sh
sudo usermod -aG docker $USER
```
20
21
You should log out after this step and log in again. You can check with the
command `groups` whether you have the docker group.
22

23
24
25
It is recommended that you clone this repository such that you have the
example configuration files at hand.

26
## Start CaosDB ##
27
28
Once you have docker installed, you only need two configuration files: One
for the reverse proxy envoy `envoy.yml` and one that defines the docker containers that
29
30
you want to use and how they can interact `docker-compose.yml`. If you did not
clone this repository before, you can copy the
31
`compose` folder of this repository to your computer and then run
32

Henrik tom Wörden's avatar
Henrik tom Wörden committed
33
34
35
```sh
docker-compose -f compose/docker-compose.yml up
```
36

37
This will download the images that are used which may take a couple of minutes.
38
Once the logs read
39

40
41
42
43
44
```
caosdb-server_1  | Starting the Jetty [HTTPS/1.1] server on port 10443
caosdb-server_1  | Starting the Jetty [HTTP/1.1] server on port 10080
caosdb-server_1  | Starting org.caosdb.server.CaosDBServer application
```
45

46
the server is ready and you can access CaosDB with your web browser under `localhost:8081`.
47
48
49
Default credentials are
- username: `admin`
- password: `caosdb`
Henrik tom Wörden's avatar
Henrik tom Wörden committed
50
51
52
53

## Stopping CaosDB ##
You can stop the containers with CTRL-C. See the documentation of docker-compose
for other options (e.g. `-d` for detach).
54

55
56
57
58
Note, that the suggested configuration provided here uses persistent volumes.
This means that data and files will be stored such that they are persistent
across restarts.

59

60
## Building the image
61
62
63
64
65

If you don't want to use the prebuilt image, e.g., because you changed something
in the Dockerfile, you can build the docker image yourself using the `docker`
command in the `docker` folder:

66
67
68
69
```sh
cd docker
DOCKER_BUILDKIT=1 docker build -t caosdb .
```
70

71
72
73
The buildkit setting allows the usage of some special features in the `Dockerfile`.

The image will be named `caosdb`.
74

75
76
77
78
79
80
81
82
### Versions of CaosDB components
If you want to build an image with specific versions of the various CaosDB
components, you can do so by using `--build-arg` options.
For example `--build-arg MYSQLBACKEND=v4.0.0` will change the version of the
sql backend.

The following arguments are available: `MYSQLBACKEND SERVER WEBUI PYLIB ADVANCEDUSERTOOLS`.

Henrik tom Wörden's avatar
Henrik tom Wörden committed
83
## SSL Certificates
84
85
86
87
If you want to use SSL certificates (and in production use, you definitely should)
you need to uncomment the respective sections in `envoy.yml` and `docker-compose.yml`.
The given configuration assumes, that the certificate files are placed in a folder
`compose/certs` and named `caosdb.key.pem` and `caosdb.cert.pem`.
88

89
90
91
92
It is assumed that `caosdb.key.pem` does not have a passphrase. You can remove
one with `openssl rsa -in oldKey.pem -out newKey.key`. If you want to use a
certificate with a passphrase instead, please refer to envoy's documentation as
to how to configure this correctly.
Henrik tom Wörden's avatar
Henrik tom Wörden committed
93

94
95

## Configuration
96
97

### The CaosDB server
98
99
You can include alternative configuration settings for the CaosDB server.
Please see the [server documentation](https://docs.indiscale.com/caosdb-server/administration/configuration.html).
100

101
102
It is recommended to add settings in files in the `server.conf.d` folder. E.g.
`caosdb-server/conf/ext/server.conf.d/50-example.conf`
103

104
Uncomment the corresponding section in the `docker-compose.yml`
105

106
107
108
109
110
### Including large data folders
Often users do not want to copy all files into CaosDB but instead want to make
whole filesystems available to the CaosDB server. This can be achieved by mounting
the corresponding filesystem into the container. You can do this by uncommenting
the volume section that bind mounts some path (that you must set) to `.../extroot`.
111
112
113



Henrik tom Wörden's avatar
Henrik tom Wörden committed
114
115
116
### Bind IP
If you want your server to be accessible from other computers, you need to change
the bind ip. Adjust the compose file accordingly.
117
118
119
120
121
122


## Integration Tests

## Troubleshooting

123
124
### Envoy cannot read SSL certificate files
Make sure that the user that is used by envoy has read permissions.