Skip to content

Latest commit

 

History

History
239 lines (170 loc) · 5.64 KB

CONTRIBUTING.md

File metadata and controls

239 lines (170 loc) · 5.64 KB

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 porject
├── 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

🐋 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.

Note that a env variable could be passed to change the port, it is hardcoded for now.
It could be a nice and easy first issue and pull request if you would like to help :).

Now you can run the CLI:

  • Using cargo make

    cargo make run-cli version

  • Using cargo

    cargo run --bin nanocl version

🧪 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

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

👌 Usefull Command

Some usefull 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

  • Generate ssl cert from certbot

    nanocl cargo -n system exec nproxy -- certbot --nginx --email email@email.com --agree-tos -d your-domain.com

Version bumping

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