Skip to content

Latest commit

 

History

History
238 lines (172 loc) · 5.52 KB

contributing.md

File metadata and controls

238 lines (172 loc) · 5.52 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 used for the project
│       ├── repositories # Functions to make SQL requests
│       ├── services # Function to accept http requests
│       ├── subsystem # Function executed before starting the server
│       └── utils # Utils functions for the project
├── ncddns # Nanocl Controller Daemon DNS REST API
│   ├── specs # OpenApi specification
│   ├── tests # Test configurations
│   └── src # Rust source code
├── ncdproxy # 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
├── nanocld_client # A nanocld client
│   └── src # The rust source code
├── nanocl_utils # A collection of utils used in the project
│   └── src # The rust source code
└── nanocl_stubs # Shared data structure mostly used as input and output of out DAEMON
    └── src # The rust source code

💾 Installation

Clone the repository:

git clone https://github.com/nxthat/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:

docker compose up

🐋 Docker Desktop

If you can have Docker installed normally with his default socket on /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 need to update this line:

volumes:
  - /run/docker.sock:/run/docker.sock # by /home/{your_user}/.docker/desktop/docker.sock:/run/docker.sock

On the nanocld service, afterward you can start the daemon using:

docker compose up

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 :).

To use the CLI you need correct permission on /run/nanocl

sudo chmod -R /run/nanocl

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.
Then be sure to have correct permission set on /run/nanocl You also need this entry in your /etc/hosts

127.0.0.1 nstore.nanocl.internal

  • 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

👌 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