This document describes how to build the following nexus clients:
- How to manage a Nexus development server: useful for developping or contributing to Nexus server and easily testing it
- How to manage a Nexus production server: required if you want to install Nexus server in a production environment
- How to build and run various Nexus clients
-`nexush`
-`nexus-cli`
-`nexus-exam`
# Managing Nexus development server
### Building nexush and nexus-cli
## Building and installing dev server
To build `nexush` or `nexus-cli` binaries, go into `src/nexush` or `src/nexus-cli` and run:
```
make build
```
This command statically builds binaries for all supported combinations of operating systems and architectures into the `build` directory.
1. export PREFIX=~/tmp
1. make build_srv
1. make install_dev_srv
To removes all generated files, run:
```
make clean
```
## Running dev server
## Building nexus-exam
1. export PREFIX=~/tmp
1. make run_srv
To build the `nexus-exam` binary, go to `nexus-client.git/src/nexus-exam` and run:
```
go build
```
## Updating dev server
For now, the only supported combination of operating system and architecture is Linux amd64. Furthermore, `nexus-exam` cannot be built statically (on Ubuntu 20.04 and 22.04 at least) as some static libraries are missing.
1. Stop server by pressing CTRL-C in the terminal it was started
1. make build_srv update_srv
Finally, run the following to strip symbols and reduce the binary size:
```
strip -s nexus-exam
```
# Managing Nexus production server
## Building and installing prod server
1. Modify `config/certs/ca.info` to your liking
1. Modify `config/certs/nexus-server.info` to your liking
1. export PREFIX=/usr/local
1. make build_srv
1. sudo install_prod_srv
## Starting prod server
1. systemctl start nexus-service
## Updating prod server
1. make build_srv
1. systemctl stop nexus-service
1. export PREFIX=/usr/local
1. sudo make uninstall_prod_srv
1. systemctl start nexus-service
# Managing Nexus clients
## Building nexush
1. export PREFIX=~/tmp
1. make build_nexush
Similar targets for other clients: "build_nexus-cli" and "build_nexus-exam"
## Running nexush
1. make run_nexush EMAIL=admin@nexus.org
## Running nexus-exam
For now, the only supported combination of OS and architecture for nexus-exam is Linux amd64. Furthermore, it cannot be built statically (on Ubuntu 20.04 and 22.04 at least) as some static libraries are missing.
1. make run_nexus-exam
# Run Nexus validation tests
A variety of tests can be performed in the hope to locate potentiel bugs in the code.
These tests expect a template that includes "xubuntu" in its name, otherwise it will spill out errors.
Furthermore, make sure the login you specify below has access to this template and has most capabilities enabled.
As mentioned above, the script is simply a `Makefile` located at the root of the git repository. The Makefile's usage is as follow (type `make` to display the help):
```
nexus-server installation script.
Available targets:
build build the nexus-server binaries [run as non-root]
install create the nexus user, create certificates and install
nexus-server into /nexus-server [run as root]
update update the nexus-server binaries [run as root]
uninstall remove the nexus user and everything that was installed
[run as root]
"install", "update" and "uninstall" targets require PREFIX to be set.
PREFIX specifies where to find nexus-server. For instance:
make install PREFIX=/usr/local
will install nexus-server into /usr/local/nexus-server
```
As mentioned above, the script is simply a `Makefile` located at the root of the git repository.
### Configuring certificates
Certificates are required to ensure encrypted communication (TLS) with nexus clients. The installation script creates the required certificates, but you must still edit a few fields specific to your system.
Edit `pki/server-nexus.info` and change the following fields to match your server:
-`cn`
-`dns_name`
-`ip_address`
Edit `config/certs/nexus-server.info` and change the following fields to your liking: `organization`, `cn`, `dns_name` and `ip_address`.
Also, edit `config/certs/ca.info` and change the `cn` field accordingly.
### Configuring the service
By default, the service listens to port 1077.
If you would like the service to listen to a different port, edit `conf/nexus-server.service` and change the line ending in `-p 1077` with the port of your choice. Beware however, that the port number **must be** between 1025 and 1099!
Furthermore, each running VM listens to a port randomly chosen in the range [50000,52000] inclusive. This range can be changed in`src/consts.go`.
### Building nexus-server from source
As a non-root user, run the following command:
```
make build
```
By default, the service listens to port 1077. If you would like the service (API) to listen to a different port, edit `config/systemd/nexus-server.service` and change the line ending in `-p 1077` with a port in the range [1025,1099] inclusive. If you wish to change this range, modify `APIPortMin` and `APIPortMax` in `src/server/consts/consts.go`.
You should get the following output:
```
Building nexus-server
OK
Building genpwd
OK
```
Furthermore, each running VM listens to a port randomly chosen in the range [1100,65535] inclusive. If you wish to change this range, modify `VMSpiceMinPort` and `VMSpiceMaxPort` in `src/server/consts/consts.go`.
### Installing nexus-server
### Building nexus-server and installing nexus-server
A `PREFIX` environment variable is used to specify where nexus-server must be installed. Let's assume we want `nexus-server` to reside in `/usr/local/`.
Run the following command as **root** or with `sudo`:
```
sudo make install PREFIX=/usr/local
```
You should get the following output (truncated as it's quite long):
Run the following commands:
```
Installing nexus-server in /usr/local/nexus-server
Creating nexus group
addgroup: The group `nexus' already exists as a system group. Exiting.
OK
Creating nexus user
The system user `nexus' already exists. Exiting.
OK
Adding nexus user to kvm group
OK
Creating nexus-server file hierarchy in /usr/local/nexus-server
OK
Copying initial users config
OK
Copying binaries
OK
Generating certificates
[... TRUNCATED ...]
Signing certificate...
OK
Moving certificates
OK
Setting file permissions and owner
OK
Copying nexus-server crond task
OK
Copying nexus-server service file
OK
Reloading systemd configuration
OK
Successfully installed nexus-server into /usr/local/nexus-server
export PREFIX=/usr/local
make build_srv
sudo install_prod_srv
```
The command above:
The last command above:
- Creates a `nexus` user and group to run the service.
- Creates the file/directory hierarchy in the specified directory.
...
...
@@ -671,7 +601,7 @@ Whenever a new version of **nexus-server** is released, the binaries must be upd
Go to the root source directory `nexus-server.git` and as a non-root user, build the binaries:
```
make build
make build_srv
```
Then, as root (or sudo), stop the **nexus-server** systemd service:
