Skip to content
This repository has been archived by the owner on Feb 28, 2023. It is now read-only.

Commit

Permalink
4-space-indent all code blocks
Browse files Browse the repository at this point in the history 
so that the bullet list retains correct indentation
  • Loading branch information
Shay Bergmann committed Oct 20, 2020
1 parent 733df8f commit d8667c7
Showing 1 changed file with 113 additions and 113 deletions.
226 changes: 113 additions & 113 deletions README.md
View file
Expand Up @@ -15,13 +15,13 @@
* If you don't already have Nix installed, please install it by following the directions at [Nix Installation](https://nixos.org/manual/nix/stable/#chap-installation).
* A multi-user Nix installation is recommended over a single-user Nix installation as the multi-user install has advantages, such as being able to handle multiple builds in parallel.
* To install Nix as a single-user install, the following command can be run as a regular non-root user with `sudo` access:
```
$ sh <(curl -L https://nixos.org/nix/install) --no-daemon
```
```
$ sh <(curl -L https://nixos.org/nix/install) --no-daemon
```
* To install Nix as a multi-user install, the following command can be run as a regular non-root user with `sudo` access:
```
$ sh <(curl -L https://nixos.org/nix/install) --daemon
```
```
$ sh <(curl -L https://nixos.org/nix/install) --daemon
```
* After performing a Nix single or multi-user install, any shells should be exited and re-entered to ensure the new Nix settings take effect in the environment.
* Alternatively, the operating system [NixOS](https://nixos.org/manual/nixos/stable/#sec-installation) can be used which includes a Nix installation.

Expand All @@ -30,22 +30,22 @@ $ sh <(curl -L https://nixos.org/nix/install) --daemon

* After Nix is installed, Nix needs to have a few things customized to utilize new features and a project specific cache.
* For a Nix single-user install, the Nix configuration file will be found at the following location. Create this diretory structure and file if it does not yet exist:
```
$ mkdir -p ~/.config/nix
$ touch ~/.config/nix/nix.conf
```
```
$ mkdir -p ~/.config/nix
$ touch ~/.config/nix/nix.conf
```

* For a Nix multi-user install, the Nix configuration file will be found at the following location:
```
$ ls -la /etc/nix/nix.conf
```
```
$ ls -la /etc/nix/nix.conf
```

* The following configuration lines need to be added to the Nix configuration:
```
experimental-features = nix-command flakes ca-references
substituters = https://cache.nixos.org https://mantis-ops.cachix.org
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= mantis-ops.cachix.org-1:SornDcX8/9rFrpTjU+mAAb26sF8mUpnxgXNjmKGcglQ=
```
```
experimental-features = nix-command flakes ca-references
substituters = https://cache.nixos.org https://mantis-ops.cachix.org
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= mantis-ops.cachix.org-1:SornDcX8/9rFrpTjU+mAAb26sF8mUpnxgXNjmKGcglQ=
```

* Additionally, for a Nix multi-user install:
* The following line should also be added, where `<YOUR_USERNAME>` is substituted with your actual non-root username:
Expand All @@ -65,49 +65,49 @@ trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDS

* If lines for `experimental-features`, `substituters`, `trusted-public-keys` or `trusted-users` already exist in your Nix configuration file, then merge the lines above with the content that is already pre-existing in your Nix configuration.
* For a NixOS installation, the following declarative code snippet in the machine NixOS configuration file, usually found at `/etc/nixos/configuration.nix`, followed by a `sudo nixos-rebuild switch` will add and activate the modified Nix configuration:
```
nix.binaryCaches = [
"https://cache.nixos.org/"
"https://mantis-ops.cachix.org"
];
nix.binaryCachePublicKeys = [
"cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
"mantis-ops.cachix.org-1:SornDcX8/9rFrpTjU+mAAb26sF8mUpnxgXNjmKGcglQ="
];
nix.extraOptions = ''
experimental-features = nix-command flakes ca-references
'';
```
```
nix.binaryCaches = [
"https://cache.nixos.org/"
"https://mantis-ops.cachix.org"
];
nix.binaryCachePublicKeys = [
"cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
"mantis-ops.cachix.org-1:SornDcX8/9rFrpTjU+mAAb26sF8mUpnxgXNjmKGcglQ="
];
nix.extraOptions = ''
experimental-features = nix-command flakes ca-references
'';
```


### Nix Shell

* Once Nix is installed and configured, clone the mantis-ops repo to your local machine and enter the local repository directory:
```
# For cloning using a github registered key:
$ git clone git@github.com:input-output-hk/mantis-ops
# or, for cloning without a github registered key:
$ git clone https://github.com/input-output-hk/mantis-ops
$ cd mantis-ops
```
```
# For cloning using a github registered key:
$ git clone git@github.com:input-output-hk/mantis-ops
# or, for cloning without a github registered key:
$ git clone https://github.com/input-output-hk/mantis-ops
$ cd mantis-ops
```

* After entering the repository directory, the following command needs to be run ONLY ONCE. This will set up all the required dependencies for the nix-shell environment, including Nix flakes support and install them into the nix user profile:
```
nix-shell --run '
( nix build .#nixFlakes -o devShell
nix-env -i ./devShell
rm devShell
) || nix profile install github:input-output-hk/mantis-ops#nixFlakes
'
```
```
nix-shell --run '
( nix build .#nixFlakes -o devShell
nix-env -i ./devShell
rm devShell
) || nix profile install github:input-output-hk/mantis-ops#nixFlakes
'
```

* Finally, enter the development environment with the following command. This command should be executed whenever you have a new shell and you'd like to enter the development enviroment:
```
nix develop
```
```
nix develop
```


### Github Access Token
Expand All @@ -126,42 +126,42 @@ nix develop
### Vault Authentication

* From your nix development environment, obtain a vault token by supplying the following command with your github mantis-ops personal access token when prompted:
```
$ vault login -method github -path github-employees
```
```
$ vault login -method github -path github-employees
```

* After logging into vault, if you need to see your vault token again or review information associated with your token, you can view it with the following command:
```
$ vault token lookup
```
```
$ vault token lookup
```

* To see only your vault token, without additional information, use the following command:
```
$ vault print token
```
```
$ vault print token
```


### Nomad Authentication

* After logging into vault, you can obtain a nomad token for the developer role with the following command:
```
$ vault read -field secret_id nomad/creds/developer
```
```
$ vault read -field secret_id nomad/creds/developer
```

* Optionally, you can export this token locally to have access to the nomad cli which will enable additional cli debugging capabilities. For example:
```
# Export the nomad developer token:
$ export NOMAD_TOKEN="$(vault read -field secret_id nomad/creds/developer)"
# Now the nomad cli becomes available.
# The following are some example commands that may be useful:
$ nomad status
$ nomad status mantis
$ nomad alloc logs $ALLOC_ID > mantis-$ALLOC_ID.log
$ nomad job stop mantis
# etc.
```
```
# Export the nomad developer token:
$ export NOMAD_TOKEN="$(vault read -field secret_id nomad/creds/developer)"
# Now the nomad cli becomes available.
# The following are some example commands that may be useful:
$ nomad status
$ nomad status mantis
$ nomad alloc logs $ALLOC_ID > mantis-$ALLOC_ID.log
$ nomad job stop mantis
# etc.
```

* The nomad token is also used to authenticate to the mantis-ops Nomad web UI at: https://nomad.mantis.ws/
* In the upper right hand corner of the Nomad web UI, click "ACL Tokens".
Expand All @@ -172,9 +172,9 @@ $ nomad job stop mantis
### Consul Authentication

* Optionally, a Consul token can be exported in order to use Consul templates, described below:
```
export CONSUL_HTTP_TOKEN="$(vault read -field token consul/creds/developer)"
```
```
export CONSUL_HTTP_TOKEN="$(vault read -field token consul/creds/developer)"
```


### Mantis Ops Web UI Resources
Expand All @@ -199,28 +199,28 @@ export CONSUL_HTTP_TOKEN="$(vault read -field token consul/creds/developer)"
* Querying logs by job identifier can be done through the "Explore" icon in the left vertical panel.
* If you don't see this "Explore" icon which looks like a compass, request "Editor" access from DevOps.
* Examples of log queries to the `Loki` log datasource in Grafana are:
```
# In the "Log labels" field enter the following to search for all logs related to the `mantis-1` taskgroup:
{syslog_identifier="mantis-1"}
# In the "Log labels" field enter the following to search for all logs related to the `mantis-1` taskgroup
# and filter for DAG events:
{syslog_identifier="mantis-1"} |~ "DAG"
```
```
# In the "Log labels" field enter the following to search for all logs related to the `mantis-1` taskgroup:
{syslog_identifier="mantis-1"}
# In the "Log labels" field enter the following to search for all logs related to the `mantis-1` taskgroup
# and filter for DAG events:
{syslog_identifier="mantis-1"} |~ "DAG"
```


### Updating the Mantis source used for Deployments

* Near the top of the `./overlay.nix` file of the mantis-ops repository, the mantis commit ref is seen, where $COMMIT represents the actual commit revision and $BRANCH represents the branch of the commit, typically `develop`:
```
mantis-source = builtins.fetchGit {
url = "https://github.com/input-output-hk/mantis";
rev = "$COMMIT";
ref = "$BRANCH";
submodules = true;
};
```
```
mantis-source = builtins.fetchGit {
url = "https://github.com/input-output-hk/mantis";
rev = "$COMMIT";
ref = "$BRANCH";
submodules = true;
};
```
* To update the commit that a mantis job will be run with, update the `rev` and `ref` fields with the appropriate git commit revision and git commit branch.
* It is a good idea to commit mantis-source updates since a github action will automatically push the build product to cachix for faster job deployments for everyone on the team.

Expand All @@ -230,9 +230,9 @@ export CONSUL_HTTP_TOKEN="$(vault read -field token consul/creds/developer)"
* Presently, there is no requirement to commit changes from a mantis job definition to the repository in order to deploy the job.
* To minimize confusion in the team about what job definition is running on the testnet, any changes to the mantis job made and deployed should be committed.
* To run a mantis job by deploying it to the testnet, execute the following command:
```
$ nix run .#nomadJobs.mantis.run
```
```
$ nix run .#nomadJobs.mantis.run
```
* Versioning information about the deployment, including changes from the last version deployed, can be viewed in the Nomad UI in the [Versions](https://nomad.mantis.ws/ui/jobs/mantis/versions) section.


Expand Down Expand Up @@ -271,9 +271,9 @@ $ nix run .#nomadJobs.mantis.run
* Additional bootstrap miner state only needs to be generated if the total number to be scaled to exceeds the number which currently exists (6 at the time of writing).
* Pre-existing bootstrap node state can be viewed at the [testnet Vault kv](https://vault.mantis.ws/ui/vault/secrets/kv/list/nomad-cluster/testnet/) path.
* This state pre-generation is done with the following command:
```
nix run .#generate-mantis-keys $TOTAL_NUM_BOOTSTRAP_NODES
```
```
nix run .#generate-mantis-keys $TOTAL_NUM_BOOTSTRAP_NODES
```


### Scaling Infrastructure Requirements
Expand All @@ -291,18 +291,18 @@ nix run .#generate-mantis-keys $TOTAL_NUM_BOOTSTRAP_NODES

* For debugging purposes, it can be helpful to generate a real time map of running taskgroups and the associated public IP and node hostname (containing internal IP).
* To do this we can use a Consul template:
```
$ consul-template -template templates/map.tmpl -once -dry -log-level err
```
```
$ consul-template -template templates/map.tmpl -once -dry -log-level err
```


### Starting a Mantis Local Node Connected to Testnet

* A local mantis node can be build and run connected to the testnet:
```
# Build the mantis executables and configuration files
$ nix build .#mantis -o mantis-node
# Run a local mantis node against the testnet bootstrap cluster
$ consul-template -template templates/mantis.tmpl:mantis-local.conf -exec './mantis-node/bin/mantis -Dconfig.file=./mantis-local.conf'
```
```
# Build the mantis executables and configuration files
$ nix build .#mantis -o mantis-node
# Run a local mantis node against the testnet bootstrap cluster
$ consul-template -template templates/mantis.tmpl:mantis-local.conf -exec './mantis-node/bin/mantis -Dconfig.file=./mantis-local.conf'
```

0 comments on commit d8667c7

Please sign in to comment.