Skip to content

Latest commit

 

History

History
249 lines (179 loc) · 5.82 KB

CONTRIBUTING.md

File metadata and controls

249 lines (179 loc) · 5.82 KB
Raw

Contribution guide

Joining an unknown project can be difficult, even if you have some experience.
This documentation will help you to setup Nanocl in development.
Note: Nanocl heavily utilizes ntex as client and server

📙 Table of Contents

Project Structure

Nanocl is using a mono repository structure.

bin # Binaries (executable)
├── nanocl # Nanocl CLI
│   └── src # Rust source code
│       ├── commands # Function that executes commands
│       ├── models # Data structure used for the project
│       └── utils # Utils functions for the project
├── nanocld # Nanocl DAEMON REST API
│   ├── migrations # SQL table definition to generate schema.rs with diesel
│   ├── specs # OpenApi specification
│   └── src # Rust source code
│       ├── models # Data structure and database model used for the project
│       ├── services # Function to accept http requests
│       └── utils # Utils functions for the project
├── ncdns # Nanocl Controller Daemon DNS REST API
│   ├── specs # OpenApi specification
│   ├── tests # Test configurations
│   └── src # Rust source code
├── ncproxy # Nanocl Controller Daemon PROXY REST API
│   ├── specs # OpenApi specification
│   ├── tests # Test configuration
│   └── src # Rust source code
├── ndns # Source to build custom dnsmasq container image
└── nproxy # Source to build custom nginx container image
crates # Shared Libraries
├── nanocl_error # Error utils used in the project
├── nanocl_stubs # Shared data structure mostly used as input and output of the DAEMON
├── nanocl_utils # A collection of utils used in the project
└── nanocld_client # A nanocld client

Installation

Clone the repository:

git clone https://github.com/next-hat/nanocl

To build and run Nanocl you will need these dependencies

  • rust >= 1.67

  • docker >= 1.41

  • gcc

  • make

  • libpq-dev

  • openssl-dev

Ubuntu

If you are running ubuntu, the following scripts will install the required dependencies:

./scripts/ubuntu.deps.sh

If you need docker:

./scripts/install_docker.ubuntu.sh

Rust

To install rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Afterwards install rust devtools required to run Nanocl

./scripts/rust.deps.sh

Running

Make sure your are in docker group, if not then you can add yourself:

sudo usermod -aG docker $USER
newgrp docker

Before running Nanocl we will need to download and build some docker images:

./scripts/install_dev_image.sh

Then spin up Nanocl services using docker compose.

Note

You need use vpnkit profile for docker desktop see below

docker compose up

This will start the following services:

  • nstore - Nanocl Store
  • nmetrics - Nanocl Metrics
  • ndaemon - Nanocl Daemon

If you need to work with the proxy or the dns, you can start them with:

docker compose --profile proxy --profile dns up

Docker Desktop

Important

With Docker Desktop you'll need an additional container, to enable it run docker compose with vpnkit profile

docker compose --profile vpnkit up

If you can have Docker installed normally with his default socket on /var/run/docker.sock you can also change the context:

docker context ls
docker context use default

In case you want to be using Docker desktop, you will not be able to reach services that aren't public.

Once started, a swagger should be available on http://localhost:8585/explorer.

Now you can run the CLI using cargo make

cargo make run-cli version

Important

If you run into a permission deny error with cargo make run-cli Be sure to chown your target directory, this error occur because it have been mounted by a docker container at first

sudo chown $USER:$USER -R target

Testing

To run tests, make sure all Nanocl services are running with docker compose up.
You also need theses entries in your /etc/hosts

127.0.0.1 store.nanocl.internal
127.0.0.1 nanocl.internal

Then you need to chown the state directory to be able to read SSL/TLS certificate to connect to the database

sudo chown $USER:$USER -R ~/.nanocl_dev

  • Run all tests

    cargo make tests

  • Run all tests with print output

    cargo make tests-debug

  • Run only daemon tests

    cargo make tests-daemon

  • Run only cli tests

    cargo make tests-cli

  • Run only client tests

    cargo make tests-client

Important

If the tests failed and you need to cleanup the state you can use the following commands:

cargo make docker-clean
sudo rm -rf ~/.nanocl_dev

On test fails make sure to remove any resource or cargo still alive after tests

Useful Command

Some useful command to know:

  • lsns - list namespaces

    lsns

  • nsenter - run program in different namespaces

    sudo nsenter -t 12267 -n ss -ltu

  • Generate a nanocld client

    docker run --rm -v $(pwd):/local openapitools/openapi-generator-cli generate -g rust -i /local/specs/v1/swagger.json -o /local/client

Version bumping

On version bump of api or proxy, example files have to be updated to the last version to avoid test failing