Creates a containerized environment for an IVIS-core instance:
- MySQL database with optional Adminer web interface
- Elasticsearch with optional Kibana web interface
- IVIS-core instance configured to use the other containers
- all behind an HTTP(S) Apache proxy
- Docker, Docker Compose
ssh-keygen
- on Windows run:
wsl -d docker-desktop
docker-desktop-wsl-prompt > sysctl -w vm.max_map_count=262144
docker-desktop-wsl-prompt > exit
- on Linux run:
run sysctl -w vm.max_map_count=262144
Generate SSH key pair for remote executor communication
./remote-exec-ssh-init.sh
To supply your own certificates:
- The keypair MUST be of ECDSA type
- due to
ssh2
package compatibility
- due to
- You must manually alter the
docker-compose
mounts for the/opt/ssh_pub
and/opt/ssh_priv
files
git clone <YOUR_IVIS_REPO>
cd ivis-core
git checkout <YOUR_IVIS_BRANCH>
Paths are relative to the ivis-containerized
repo root!
-
Navigate to your Account in the OCI Console
-
API keys -> Add API Key
-
Generate Key pair, download both key files
-
Copy configuration file preview into
config/config.txt
-
Set the
key_file
entry to/opt/oci_key
-
Copy private key file into
config/key.txt
-
Click on the Oracle Cloud Console Menu
-
Identity & Security -> Compartment -> select your compartment
-
Copy OCID of your compartment into the
config/ivis/default.yaml
compartmentId
key -
Copy tenancy ID from the configuration file preview or
config/config.txt
intoconfig/ivis/default.yaml
tenancyId
key
Pick and register 3 domain names (ivis.domain.com
, sbox.domain.com
, api.domain.com
) for the trusted, sandbox and API endpoints. Create a single SSL/TLS certificate for all of the domain names and note the location of the full chain and private key files.
Note that not every IVIS-core branch / fork might be compatible with the following!
Generate certificates (in the ivis-core
directory)
cd ./server/certs/remote/
./init.sh
./server_cert_gen.sh server <ivis> <sbox> <api>
ivis
, sbox
and api
are the registered A/CNAME DNS records for the trusted, sandbox and api endpoints respectively.
In the docker-compose.yml
file, modify the proxy
container's environment vairables to the registered domain names as well as the certificate mount locations. Also modify the database password.
In the config/ivis/default.yaml
file, modify trustedUrlBase
, sandboxUrlBase
and remoteElasticsearchBase
to use your registered domain names (just like in proxy
's environment variables).
Furthermore, update the mysql.password
key to the password used in the db
container's configuration. Finally, change the www.secret
.
(only if you generated cetificates elsewhere)
Modify the docker-compose.yml
to properly mount all required certificates (cross check the generation scripts and the docker compose file). Please note that both the Apache proxy and IVIS-core need the generated certififcates. Furthermore, modify docker-compose.yml
, config/ivis/default.yaml
and config/apache/vhosts.conf
(or even apache.conf
) to configure the ports on which you want everything to listen and set proper ServerName
, trusted/sandboxUrlBase
values. Do not forget about the database password from docker-compose.yml
and the secret used for session signing when editing the IVIS-core config.
Please be careful when modifying the files. They should work out of the box with some minor adjustments (mainly due to domain name differences). As a rule of thumb:
- data in
vhosts.conf
regards the container network (apart from theServerName
directives) and DNS names used in this file are drawn from thedocker-compose.yml
container names - data in
default.yml
regards the container network (apart from thetrusted/sandboxUrlBase
entries)
Finally,
docker compose up --build
The IVIS-Core container will time out several times before actually running with error wait-for-it.sh: timeout occurred after ...
. Just wait until the elasticsearch/database container is ready to make connections and IVIS-core will start.
WARNING: due to implementation details, this setup does not support Oracle Cloud Infrastructure extension
Modify your /etc/hosts
file (or Windows equivalent - C:\Windows\System32\drivers\etc\hosts
) to include three new hosts (for example: ivis.apache
, sbox.apache
, api.apache
) and map them onto the loopback (127.0.0.1
).
Note that not every IVIS-core branch / fork might be compatible with the following!
Generate certificates (in the ivis-core
directory)
cd ./server/certs/remote/
./init.sh
./server_cert_gen.sh server <ivis> <sbox> <api>
ivis
, sbox
and api
are the hosts you've created in the first step.
OUTDATED NOTICE: environment variables should work with the setup, though it hasn't been tested
Modify the docker-compose-dev.yml
to properly mount all required certificates and set db password. Please note that both the Apache proxy and IVIS-core need the generated certififcates. Furthermore, modify docker-compose-dev.yml
, config/ivis/default.yaml
and config/apache/vhosts.conf
(or even apache.conf
) to configure the ports on which you want everything to listen and set proper ServerName
, trusted/sandboxUrlBase
values. Do not forget about the database password from docker-compose.yml
and the secret used for session signing when editing the IVIS-core config.
In addition to that, uncomment the tapache.networks.aliases
section in docker-compose-dev.yml
and set the aliases to the hosts you've created.
- IMPORTANT: to make this a truly local instance (in case you're exposed to the internet), replace all port exposure from
1234:5678
to (quoted!)"127.0.0.1:1234:5678"
Please be careful when modifying the files. They should work out of the box with some minor adjustments (mainly due to domain name differences). As a rule of thumb:
- data in
vhosts.conf
regards the container network (apart from theServerName
directives) and DNS names used in this file are drawn from thedocker-compose-dev.yml
container names - data in
default.yml
regards the container network (apart from thetrusted/sandboxUrlBase
entries)
Finally,
docker compose -f ./docker-compose-dev.yml up --build
To prevent client rebuilding when not needed, use just
docker compose -f ./docker-compose-dev.yml up
On the other hand, to force a rebuild, use the --build
switch.
To rebuild the IVIS python package, the IVIS container must be restarted as the package build is part of the entrypoint script.
Please expect that your browser will panic about the certificates being invalid. Either ignore this or inject the local CA from ivis-core/server/remote/ca
into your browser.
Adding a remote executor requires attaching the executor to the same network.
All configuration (both executor config and the executor database entries on IVIS-core) is done with respect to the container network. E.g. you use the container names as defined in the docker-compose
files (or their network aliases) and ports facing into the container network, not the host network! The executor thus does not need to expose any ports to the host network.
This is due to the remote executor simulation. Certificates are still needed to access the remote executor and there would be close to no point in simulating the executor if the main security feature was not even present.
Though Nginx seems to provide more friendly configuration (especially with non-standard Apache Docker container paths), it proved useless in the implementation of the rest/remote/
endpoint.
This endpoint is used from the Internet by remote executors to communicate job status / perform special requests and thus must be secured by veryfiying the client. Nginx simply does not support client certificate renegotiation based on the URI location (rest/remote/*
in this case) while Apache supports it.