Forem: leone

Build a Fast GeoIP API in Rust with ntex

leone — Sat, 28 Mar 2026 19:58:29 +0000

This article shows a step by step approach to building a small, high performance GeoIP HTTP API in Rust using ntex.

In less than 120 lines of code.

Why ntex?

Runtime choice: ntex separates framework from the async runtime, letting you select implementations that best fit your latency and platform requirements.
Ecosystem: ntex has runtime-consistent crates such as ntex-redis, ntex-grpc, ntex-mqtt, and ntex-amqp so you can add integrations that match the same runtime model.
Low overhead: ntex aims for high-throughput servers and gives control over worker count and threading.

Prerequisites

Rust toolchain (stable). Install from https://rustup.rs if needed.
cargo available on PATH.
MaxMind mmdb files placed under ./mmdb available here

Install dependencies

Run these commands to add the dependencies used in this example. Each is chosen to fulfill a specific role:

ntex - the web framework.
maxminddb - reading MaxMind DB formats.
memmap2 - memory map mmdb files for fast, zero-copy reads.
lru - in process LRU cache for repeated lookups.
anyhow - ergonomic error handling for simple apps.
serde, serde_json - JSON (de)serialization for responses.
num_cpus - detect worker count.

cargo add ntex
cargo add maxminddb --features mmap
cargo add memmap2
cargo add lru
cargo add anyhow
cargo add serde --features derive
cargo add serde_json
cargo add num_cpus

Cargo.toml:

[package]
name = "geo-api"
version = "0.1.0"
edition = "2024"

[dependencies]
anyhow = "1.0.102"
lru = "0.16.3"
maxminddb = { version = "0.27.3", features = ["mmap"] }
memmap2 = "0.9.10"
ntex = { version = "3.7.0", features = ["tokio"] }
num_cpus = "1.17.0"
serde = { version = "1.0.228", features = ["derive"] }
serde_json = "1.0.149"

Create a basic endpoint

Let's start with a basic endpoint for our api:

use ntex::web;

#[derive(serde::Deserialize)]
struct GeoIpQuery {
  ip: std::net::IpAddr,
}

#[web::get("/geoip")]
async fn geoip_handler(
  query: web::types::Query<GeoIpQuery>,
) -> web::HttpResponse {
  web::HttpResponse::Ok().json(&serde_json::json!({
    "message":"ok"
  }))
}

#[ntex::main]
async fn main() -> anyhow::Result<()> {
  let srv =
    web::HttpServer::new(async move || web::App::new().service(geoip_handler))
      .workers(num_cpus::get());
  srv.bind("0.0.0.0:8585")?.run().await?;
  Ok(())
}

Test the endpoint:

cargo run
curl 'http://localhost:8585/geoip?ip=8.8.8.8' | jq

Should output:

{
  "message": "ok"
}

Implement the logic

We will use a shared AppState struct to open and memory map the mmdb files once at startup (cheap, concurrent reads). To avoid repeated mmdb work and reduce contention, the example uses a sharded LRU cache.

The following implementation has been optimized for minimal line count at the expense of some readability and error handling.

use std::hash::{Hash, Hasher};

use lru::LruCache;
use maxminddb::Reader;
use memmap2::Mmap;
use ntex::web;

const SHARD_SIZE: usize = 16;
const CACHE_SIZE: usize = 1024;

#[derive(serde::Deserialize)]
struct GeoIpQuery {
  ip: std::net::IpAddr,
}

#[derive(Clone, serde::Serialize)]
struct GeoIpResponse {
  country: Option<String>,
  city: Option<String>,
  asn: Option<String>,
}

struct CacheShard(std::sync::Mutex<LruCache<std::net::IpAddr, GeoIpResponse>>);

impl CacheShard {
  fn new() -> Self {
    let cache_size = std::num::NonZeroUsize::new(CACHE_SIZE).unwrap();
    Self(std::sync::Mutex::new(LruCache::new(cache_size)))
  }
  fn get(&self, ip: &std::net::IpAddr) -> Option<GeoIpResponse> {
    self.0.lock().ok()?.get(ip).cloned()
  }
  fn set(&self, ip: std::net::IpAddr, response: GeoIpResponse) {
    if let Ok(mut cache) = self.0.lock() {
      cache.put(ip, response);
    }
  }
}

struct AppInner(Reader<Mmap>, Reader<Mmap>, Vec<CacheShard>);

#[derive(Clone)]
struct AppState(std::sync::Arc<AppInner>);

impl AppState {
  fn open_mmap(path: &str) -> anyhow::Result<Reader<Mmap>> {
    Ok(Reader::from_source(unsafe {
      Mmap::map(&std::fs::File::open(path)?)?
    })?)
  }
  fn new() -> anyhow::Result<Self> {
    Ok(Self(std::sync::Arc::new(AppInner(
      Self::open_mmap("./mmdb/GeoLite2-City.mmdb")?,
      Self::open_mmap("./mmdb/GeoLite2-ASN.mmdb")?,
      (0..SHARD_SIZE).map(|_| CacheShard::new()).collect(),
    ))))
  }
  fn shard(&self, ip: &std::net::IpAddr) -> &CacheShard {
    let mut hasher = std::collections::hash_map::DefaultHasher::new();
    ip.hash(&mut hasher);
    &self.0.2[(hasher.finish() as usize) % SHARD_SIZE]
  }
  fn lookup(&self, ip: &std::net::IpAddr) -> anyhow::Result<GeoIpResponse> {
    let shard = self.shard(ip);
    if let Some(v) = shard.get(ip) {
      return Ok(v.to_owned());
    }
    let (country, city) = self
      .0
      .0
      .lookup(*ip)?
      .decode::<maxminddb::geoip2::City>()?
      .map(|c| {
        (
          c.country.iso_code.map(|s| s.to_owned()),
          c.city.names.english.map(|s| s.to_owned()),
        )
      })
      .unwrap_or((None, None));
    let asn = self
      .0
      .1
      .lookup(*ip)?
      .decode::<maxminddb::geoip2::Asn>()?
      .and_then(|a| a.autonomous_system_organization.map(|s| s.to_owned()));
    let result = GeoIpResponse { country, city, asn };
    shard.set(*ip, result.to_owned());
    Ok(result)
  }
}

#[web::get("/geoip")]
pub async fn geoip_handler(
  app_state: web::types::State<AppState>,
  query: web::types::Query<GeoIpQuery>,
) -> web::HttpResponse {
  match app_state.lookup(&query.ip) {
    Err(_) => web::HttpResponse::InternalServerError().finish(),
    Ok(geoip) => web::HttpResponse::Ok().json(&geoip),
  }
}

#[ntex::main]
async fn main() -> anyhow::Result<()> {
  let app_state = AppState::new()?;
  let srv = web::HttpServer::new(async move || {
    web::App::new()
      .state(app_state.clone())
      .service(geoip_handler)
  })
  .workers(num_cpus::get());
  srv.bind("0.0.0.0:8585")?.run().await?;
  Ok(())
}

What is an LRU cache and why use it?

LRU (least-recently-used) keeps the most recently accessed items and evicts the least recently accessed when full. For GeoIP lookups many requests repeat the same IPs, so an LRU gives a high hit rate and avoids repeated, relatively expensive mmdb decodes.

Why shard the cache?

Sharding splits the cache into multiple independent smaller caches (each with its own mutex). A request hashes the IP to pick a shard. This reduces lock contention under concurrent requests because only the shard for that IP is locked, improving throughput. Tune SHARD_SIZE and CACHE_SIZE to trade memory for lower contention.

Why use Arc for AppState?

AppState holds shared, read mostly resources (the mmap'd readers and the shard vector). Wrapping it in Arc gives cheap, thread safe shared ownership so each worker/handler can clone a reference to the same state without copying the underlying data. This keeps startup work minimal and avoids unnecessary cloning of large resources.

Test the service

Build and run locally:

cargo run

Try the endpoint:

curl 'http://127.0.0.1:8585/geoip?ip=8.8.8.8' | jq

Should return:

{
  "country": "US",
  "city": null,
  "asn": "Google LLC"
}

Optimize for speed

By adding these lines to your Cargo.toml you can optimize the binary for maximum speed

[profile.release]
opt-level = 3
lto = "fat"
panic = "abort"
codegen-units = 1

Benchmark the endpoint

For fun mostly I will download a random list of ips and benchmark the endpoint using vegeta

I am testing this on localhost on an Intel i9-9900K CPU.
At high request rates, my CPU is mostly the bottleneck and the benchmark doesn't really reflect real world traffic.

Assuming you have a file with ip addresses on each line you can run:

cat ips.txt | shuf \
  | awk '{print "GET http://127.0.0.1:8585/geoip?ip=" $1}' \
  | vegeta attack -rate=50000 -duration=10s \
  | vegeta report

The result I have:

Which is pretty decent, I believe. To push the fun further, let's run it at 100k RPS

cat ips.txt | shuf \
  | awk '{print "GET http://127.0.0.1:8585/geoip?ip=" $1}' \
  | vegeta attack -rate=100000 -duration=10s \
  | vegeta report

My result:

Again, this is not a real world benchmark, but it shows the GeoIP API is robust and fast.

Conclusion

Rust has a great ecosystem of crates that lets you write fast and robust services in a few lines of code!

You can see the source code on github.

Run local LLMs in under 5 minutes using Nanocl

leone — Fri, 19 Dec 2025 17:23:34 +0000

Easily deploy and manage your own AI-powered ChatGPT website using Nanocl, Ollama, and Open WebUI.

Overview

This guide will show you how to self-host an AI model using Nanocl, a lightweight container orchestration platform. By combining Nanocl with Ollama (for running large language models locally) and Open WebUI (for a user-friendly web interface), you can quickly set up your own private ChatGPT-like service.

📺 Watch the YouTube video tutorial

https://www.youtube.com/watch?v=xh5wB8J56N8

Stack Components

Nanocl: Simple, efficient container orchestration for easy deployment and scaling.
Ollama: Run large language models locally via a powerful API.
Open WebUI: Modern web interface to interact with your AI model.

Prerequisites

Before you begin, ensure you have the following installed:

1. Docker

Install Docker by following the official guide for your Linux distribution.

2. Nanocl

Install the Nanocl CLI with:

curl -fsSL https://download.next-hat.com/scripts/get-nanocl.sh | sh

Set up Nanocl's group and internal services:

sudo groupadd nanocl
sudo usermod -aG nanocl $USER
newgrp nanocl
nanocl install

For more details, see the Nanocl documentation.

3. (Optional) Nvidia Container Toolkit

If you want GPU acceleration, follow the Nvidia container toolkit installation guide.

Step 1: Deploy Ollama with Nanocl

Create a file named ollama.Statefile.yml:

ApiVersion: v0.17

Cargoes:
- Name: ollama
  Container:
    Image: docker.io/ollama/ollama:latest
    Hostname: ollama.local
    HostConfig:
      Binds:
      - ollama:/root/.ollama  # Persist Ollama data
      Runtime: nvidia         # Enable GPU support (optional)
      DeviceRequests:
      - Driver: nvidia
        Count: -1
        Capabilities: [[gpu]]

Deploy Ollama:

nanocl apply -s ollama.Statefile.yml

Step 2: Deploy Open WebUI with Nanocl

Create a file named openwebui.Statefile.yml:

ApiVersion: v0.17

Cargoes:
- Name: open-webui
  Container:
    Image: ghcr.io/open-webui/open-webui:main
    Hostname: open-webui.local
    Env:
    - OLLAMA_BASE_URL=http://ollama.local:11434  # Connect to Ollama
    HostConfig:
      Binds:
      - open-webui:/app/backend/data  # Persist WebUI data

Resources:
- Name: open-webui.local
  Kind: ncproxy.io/rule
  Data:
    Rules:
    - Domain: open-webui.local
      Network: All
      Locations:
        - Path: /
          Version: 1.1
          Headers:
          - Upgrade $http_upgrade
          - Connection "Upgrade"
          Target:
            Key: open-webui.global.c
            Port: 8080

Deploy Open WebUI:

nanocl apply -s openwebui.Statefile.yml

It will take a bit of time for Open WebUI to start up as it downloads necessary components.
You can see the download progress in the logs:

nanocl cargo logs open-webui -f

Step 3: Access Open WebUI

Add the following line to your /etc/hosts file to map the domain:

127.0.0.1 open-webui.local

Now, open your browser and go to http://open-webui.local. You should see the Open WebUI welcome screen.

1. Create Your Admin Account

Click Get Started to begin the setup process.

Fill in your details to create your admin account, then click Create Admin Account.

2. Download a Model

After logging in, click your avatar in the top right corner and select Admin Panel.

Navigate to Settings → Models. In the top right, click the download icon to open the model selection dialog.

For this example, select the gemma2:2b model and click Download.

Wait for the download to complete. The model will appear in your list of available models.

3. Start Chatting

Once the model is ready, create a new chat and say "Hi" to your AI model!

And that's it! You now have your own self-hosted AI model running with Nanocl, Ollama, and Open WebUI.

Resources

Deploy a complete media center on Nanocl

leone — Tue, 14 Oct 2025 15:52:14 +0000

Build a robust, private media center with Nanocl using Deluge, Jackett, Radarr, Sonarr, Lidarr, and Jellyfin. This guide is concise, reproducible, and secure-by-default.

Stack: Deluge (downloads), Jackett (indexers), Radarr/Sonarr/Lidarr (automation), Jellyfin (media server)
Networking: Internal DNS + gateway via Nanocl
Access: Friendly internal domains, VPN-only option
One-command deploy: nanocl state apply -s media_center.yml

Prerequisites

Linux host with Nanocl v0.17+ installed and running
Free ports 80/443 on the host (Nanocl gateway)
A data directory on the host (e.g., /opt/media) writable by your user or set via PUID/PGID

Install Nanocl if needed (requires Docker):

curl -fsSL https://download.next-hat.com/scripts/get-nanocl.sh | sh

Documentation:

Install overview: https://docs.next-hat.com/manuals/nanocl/install/overview
Post-installation: https://docs.next-hat.com/manuals/nanocl/install/post-installation

Step 1 - Create `media_center.yml`

This Statefile deploys all services with consistent domains and internal networking. Adjust domains and paths as needed. Ensure /opt/media exists on the host and is writable.

ApiVersion: v0.17

SubStates:
- Path: https://nr.next-hat.com/v0.17/deluge.yml
  Args:
  - Name: domain
    Value: deluge.local.io
  - Name: enable_internal_dns
    Value: True
  - Name: enable_internal_gateway
    Value: True
  # Optional: restrict to VPN only (see Bonus)
  # - Name: proxy-network
  #   Value: Private

- Path: https://nr.next-hat.com/v0.17/jackett.yml
  Args:
  - Name: domain
    Value: jackett.local.io
  - Name: enable_internal_dns
    Value: True
  - Name: enable_internal_gateway
    Value: True
  # - Name: proxy-network
  #   Value: Private

- Path: https://nr.next-hat.com/v0.17/radarr.yml
  Args:
  - Name: domain
    Value: radarr.local.io
  - Name: enable_internal_dns
    Value: True
  - Name: enable_internal_gateway
    Value: True
  # - Name: proxy-network
  #   Value: Private

- Path: https://nr.next-hat.com/v0.17/sonarr.yml
  Args:
  - Name: domain
    Value: sonarr.local.io
  - Name: enable_internal_dns
    Value: True
  - Name: enable_internal_gateway
    Value: True
  # - Name: proxy-network
  #   Value: Private

- Path: https://nr.next-hat.com/v0.17/lidarr.yml
  Args:
  - Name: domain
    Value: lidarr.local.io
  - Name: enable_internal_dns
    Value: True
  - Name: enable_internal_gateway
    Value: True
  # - Name: proxy-network
  #   Value: Private

- Path: https://nr.next-hat.com/v0.17/jellyfin.yml
  Args:
  - Name: domain
    Value: jellyfin.local.io
  - Name: enable_internal_dns
    Value: True
  - Name: enable_internal_gateway
    Value: True
  # - Name: proxy-network
  #   Value: Private

Tip: If your substates support PUID/PGID and media paths, set them in each substate file or via Args to match your host user (often 1000:1000) and /opt/media.

Note: You can open each registry URL (e.g., https://nr.next-hat.com/v0.17/radarr.yml) in your browser to see the available Args for that substate.

Step 2 - Apply the state

Run once to deploy everything:

nanocl state apply -s media_center.yml

Check status:

nanocl ps

Step 3 - Enable name resolution for internal domains

Nanocl’s gateway IP will serve DNS for your internal domains (e.g., deluge.local.io). If you didn’t note it yet, retrieve it now:

1) Find the gateway IP:

nanocl info

Look for network nanoclbr0 and note Gateway, typically 172.17.0.1.

2) Point your system DNS to the Nanocl gateway so the internal domains resolve:

/etc/resolv.conf is a regular file (not a symlink):

echo "nameserver 172.17.0.1" | sudo tee /etc/resolv.conf

Verify:

dig +short deluge.local.io @172.17.0.1 || true

Note: Use a VPN (see Bonus) to keep services private.

Step 4 - Post-deploy configuration

Deluge

URL: http://deluge.local.io
Default password: deluge → change immediately
Enable the “Label” plugin (Preferences → Plugins)

Jackett

URL: http://jackett.local.io
Add your preferred, legal indexers → Save → Test

Radarr

URL: http://radarr.local.io
Enable auth (Settings → Security). Example for demo: username radarr, password radarr (change in real use)
Download client (Settings → Download Clients):
- Name: Deluge
- Host: deluge.local.io, Port: 80
- Password: your updated Deluge password
- Test → Save

Indexer (Settings → Indexers): Add “Torznab” and paste the Jackett Torznab Feed URL + API Key from Jackett

Media management: set Root Folder to /media/movies (ensure the folder exists and is mounted)

Add a movie → Optional: Interactive Search to pick a release

Monitor Deluge for download progress

Jellyfin

URL: http://jellyfin.local.io
Complete setup wizard, add a Movies library pointing to /media/movies

Sonarr and Lidarr

URLs: http://sonarr.local.io and http://lidarr.local.io
Repeat Radarr’s steps: add Deluge as download client; add Jackett via Torznab; set root folders (e.g., /media/tv, /media/music)

Bonus - Lock down access with a VPN

Use a WireGuard VPN so only your devices can reach the services.
You can check my previous blog post on how to deploy wireguard on nanocl here
After your VPN is up, make each service VPN-only by adding the following Arg under each substate:

- Name: proxy-network
  Value: Private

Then re-apply:

nanocl state apply -s media_center.yml

Troubleshooting

DNS not resolving *.local.io:
- Re-check the gateway IP from nanocl info
- Ensure your system uses that IP as DNS (see Step 3)
Permissions on /opt/media:
- Set folder ownership to your PUID/PGID, e.g. sudo chown -R 1000:1000 /opt/media
- Reapply the state: nanocl state apply -rs media_center.yml
Service won’t start:
- nanocl logs -f the failing context/service for details
Authentication:
- Change all default passwords immediately and enable auth for Radarr/Sonarr/Lidarr/Jellyfin

Disclaimer

This guide is for educational purposes only. Use only legal sources and respect copyright laws in your jurisdiction.

References

Nanocl docs: https://docs.next-hat.com/
Statefile reference: https://docs.next-hat.com/references/nanocl/statefile
Statefile registry: https://nr.next-hat.com/

Deploy Vaultwarden on Nanocl

leone — Wed, 17 Sep 2025 06:52:03 +0000

Today we are going to see how to deploy Vaultwarden on Nanocl to take back the control of your passwords.

Vaultwarden is an open-source password management solution that is a lightweight alternative to Bitwarden. It is designed to be self-hosted and provides a secure way to store and manage passwords, notes, and other sensitive information. It is built using Rust and offers a web interface, and is compatible with Bitwarden
extensions and apps.

Nanocl is a container orchestration platform that allows you to manage and deploy containerized applications easily. It provides a simple and efficient way to run containers on your infrastructure, making it easier to manage and scale your applications.

Prerequisites

Before we begin, make sure you have the following prerequisites.

Docker

Follow the official Docker installation guide for your Linux distribution. It's quick and easy!

Nanocl

Download and install the Nanocl CLI binary with this simple command:

curl -fsSL https://download.next-hat.com/scripts/get-nanocl.sh | sh

Then create a Nanocl group and install Nanocl's internal services:

sudo groupadd nanocl
sudo usermod -aG nanocl $USER
newgrp nanocl
nanocl install

For more information, check the Nanocl documentation.

Deploy Vaultwarden

Since Vaultwarden uses a secure context for the [Web Crypto API][web-crypto-api], it is recommended to use SSL/TLS encryption. You can use a self-signed certificate or obtain one from a trusted Certificate Authority (CA) like Let's Encrypt.
In this guide we will use a self-signed certificate.

Create a self-signed SSL certificate (basic)

You can create a basic self-signed SSL certificate for your domain using the openssl-self-signed.yml job Statefile already ready to use from the Nanocl registry. Replace <your-domain> with the domain you wish to host vaultwarden on.

nanocl state apply -fs nr.next-hat.com/v0.17/openssl-self-signed.yml -- --domain <your-domain>

This job will create a self-signed SSL certificate and store it as a Nanocl secret named tls.<your-domain>.

Create a self-signed SSL certificate (advanced)

If you want to be able to use the desktop app and the Android/iOS app, you need a self-signed certificate that is trusted by your operating system.
You can do this by creating your own Certificate Authority (CA) and then issuing a certificate for your domain signed by that CA.
Afterward, import the CA certificate into your operating system trust store.

# Generate CA private key (4096-bit is good for CA)
openssl genrsa -out myCA.key 4096
# Generate self-signed root certificate (valid 10 years here)
openssl req -x509 -new -nodes -key myCA.key -sha256 -days 3650 \
  -out myCA.pem -subj "/CN=Vaultwarden CA"
# Generate server private key and certificate signing request (2048-bit is standard)
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr -subj "/CN=<your-domain>"
# Create a config file for the SAN extension
echo """
[v3_req]
subjectAltName = @alt_names

[alt_names]
DNS.1 = <your-domain>
IP.1 = <your-ip-address>
""" > san.cnf

# Sign the server certificate with the CA (valid 825 days here)
openssl x509 -req -in server.csr -CA myCA.pem -CAkey myCA.key \
  -CAcreateserial -out server.crt -days 825 -sha256 \
  -extfile san.cnf -extensions v3_req

# Convert to DER format for browsers and OS trust stores
openssl x509 -outform der -in myCA.pem -out myCA.der

Then create a Nanocl secret to store the certificate and key to use it with the proxy:

nanocl secret create tls.<your-domain> tls --certificate-path ./server.crt --certificate-key-path ./server.key

Then import the myCA.der file into your operating system trust store.

Note: Only import a private CA you fully control. Trusting a CA gives it authority to sign any certificate for your system.

Apply the Vaultwarden Statefile

Now you can deploy Vaultwarden using the vaultwarden.yml cargo Statefile from the Nanocl registry. Replace <your-domain> with your domain and <your-network> with the Nanocl network you want to connect the container to (default is All).
You can see the options available in the Nanocl documentation for the proxy rule.

Network behavior:

All: Binds the proxy to all available IP addresses on the host (publicly reachable if ports are exposed).
Internal: Binds only to the Nanocl internal gateway; the service is then only reachable over your configured VPN (e.g. WireGuard).

nanocl state apply -s nr.next-hat.com/v0.17/vaultwarden.yml -- --domain <your-domain> --secret-cert tls.<your-domain>

If you want to store the Vaultwarden data on a specific path on your host, you can use the --data-path argument to specify the path (default is /opt/containers/vaultwarden).

nanocl state apply -s nr.next-hat.com/v0.17/vaultwarden.yml -- --domain <your-domain> --secret-cert tls.<your-domain> --data-path /path/to/your/data

In a more general way you can see all the arguments available by running:

nanocl state man -s nr.next-hat.com/v0.17/vaultwarden.yml

If you followed my previous blog on how to deploy WireGuard on Nanocl,
you can use the argument --network Internal to have Vaultwarden only accessible from your WireGuard VPN.

nanocl state apply -s nr.next-hat.com/v0.17/vaultwarden.yml -- --domain <your-domain> --secret-cert tls.<your-domain> --network Internal

And that's it! You have successfully deployed Vaultwarden on Nanocl.

Accessing Vaultwarden

If you deployed it on a public domain, access it at https://<your-domain> in your browser. If you deployed it locally, add this line to your /etc/hosts file:

127.0.0.1 <your-domain>

Then navigate to https://<your-domain> in your web browser.
You may see an SSL warning if you used the basic self-signed certificate. If you imported your private CA, restart your browser so the trust store reloads. Proceed to create an account to log in.

Then download the Bitwarden app or browser extension from this link and connect it to your self-hosted Vaultwarden instance. Choose the "Self-hosted" option and enter your domain.

Next Steps

To further harden and operationalize your deployment:

Configure regular off-host backups of the data directory using Nanocl scheduled jobs.
Monitor container logs periodically for failed login attempts.
Keep Nanocl and Vaultwarden images up to date (pull and re-apply state periodically).

Conclusion

You have now deployed Vaultwarden on Nanocl with TLS using either a quick self-signed certificate or a locally trusted CA. This setup lets you retain control over your credentials while remaining compatible with official Bitwarden clients.

How to easily create a CLI in Rust using clap and clap_mangen

leone — Tue, 09 Sep 2025 18:45:06 +0000

Define your CLI once with clap derive, run it at runtime, and auto-generate man pages at build time with clap_mangen all from the same source of truth. For the full working example, see:
https://github.com/0xle0ne/clap-mangen-example

What's a "man page" and why care?

"man" stands for manual. On Unix-like systems, man <topic> opens documentation in your terminal (e.g., man ls). Shipping man pages with your CLI means:

Built-in help offline: users can read docs without internet.
Consistent UX: mycli, mycli --help, and man mycli all tell the same story.
Easy discovery: man -k mycli (apropos) lets users find related commands.

Quick setup

Install dependencies first, then you're ready to follow along:

cargo add clap --features derive
cargo add clap --build --features derive
cargo add clap_mangen --build

This yields a Cargo.toml like:

[package]
name = "mycli"
version = "0.1.0"
edition = "2021"
build = "build.rs"

[dependencies]
clap = { version = "4", features = ["derive"] }

[build-dependencies]
clap = { version = "4", features = ["derive"] }
clap_mangen = "0.2"

Why this is neat

Single source of truth: the derive types drive runtime parsing and documentation.
No stale docs: man pages regenerate on build when the CLI changes.
Great for packaging: ship target/man/*.1 or install them into /usr/share/man.
Works with nested subcommands out of the box.

The CLI definition (derive)

We define the entire CLI under src/cli.rs using clap derive. Both the binary and the build script reuse these types.

// in src/cli.rs
use clap::{Command, CommandFactory, Parser};

// Longer description used for the top-level man page section.
const LONG_ABOUT: &str = r#"
mycli is a tiny example CLI demonstrating auto-generated man pages with clap and clap_mangen.

It showcases:
    - Nested subcommands (e.g., `config get`, `config set`)
    - Rich help/usage text derived from a single source of truth
    - Build-time man page generation to `target/man/`

Top-level commands:
    - config: manage configuration values (get/set)
    - server: run a demo server (addr/port/verbosity)
    - remote: add or remove a remote by name
"#;

/// mycli — a tiny example CLI used to demonstrate auto-generated man pages.
#[derive(Debug, Parser)]
#[command(
    name = "mycli",
    about = "Example CLI with nested subcommands and man page generation",
    long_about = LONG_ABOUT,
    version
)]
pub struct Cli {
    /// Top-level subcommand to execute
    #[command(subcommand)]
    pub command: Commands,
}

Minimal runtime: `main.rs`

At runtime, you parse once and dispatch to the selected subcommand. Here's the essence from src/main.rs:

use clap::Parser;

mod cli;

fn main() {
    let opts = cli::Cli::parse();
    match opts.command {
        cli::Commands::Server(s) => {
            println!("server start on {}:{} (verbosity: {})", s.addr, s.port, s.verbose);
        }
        cli::Commands::Remote(r) => {
            if r.remove {
                println!("remote removed: {}", r.name);
            } else if let Some(url) = r.url {
                println!("remote added: {} -> {}", r.name, url);
            } else {
                println!("remote info requested: {}", r.name);
            }
        }
        cli::Commands::Config(cfg) => match cfg.action {
            cli::ConfigAction::Get(g) => println!("config get {} (format: {:?})", g.key, g.format),
            cli::ConfigAction::Set(s) => println!("config set {}={} (global: {})", s.key, s.value, s.global),
        },
    }
}

Sharing CLI with `build.rs`

build.rs compiles as a separate crate, so we include the same src/cli.rs (and ensure clap is available in [build-dependencies] with features=["derive"]).

// in build.rs
mod cli {
    include!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/cli.rs"));
}

let mut cmd = <cli::Cli as clap::CommandFactory>::command();

Generating man pages recursively

clap_mangen can generate man pages for the root command and all nested subcommands with a single call:

let out_dir = manifest_dir.join("target").join("man");
std::fs::create_dir_all(&out_dir)?;
let mut cmd = <cli::Cli as clap::CommandFactory>::command();
clap_mangen::generate_to(&mut cmd, &out_dir)?; // writes mycli.1, mycli-config.1, mycli-config-get.1, etc.

The build script prints a cargo:warning showing where files were written.

How the pieces fit together

Single source of truth: src/cli.rs contains all clap derive types for your CLI. Both runtime and the build script include this file so help text and structure never drift.

1) Runtime parsing (src/main.rs)
- Cli::parse() builds values from the command line.
- A simple match dispatches to the chosen subcommand.

2) Build-time docs (build.rs)
- Includes src/cli.rs so it has the same Command layout.
- Calls clap_mangen::generate_to on the root Command.
- Recursively writes man pages for the root and every subcommand into target/man/.

3) Benefits
- No duplicate specs for help vs. docs.
- Man pages regenerate automatically on build when the CLI changes.
- Great for packaging: ship target/man/*.1 or install them into /usr/share/man.

Try it locally

cargo build
ls target/man
man -l target/man/mycli.1          # root command
man -l target/man/mycli-config-get.1  # nested subcommand

Caveats & tradeoffs

build.rs runs on every build; heavy generation can slow iterative cycles. For bigger doc pipelines, consider a cargo xtask instead and run it on demand or in CI.
Some doc hosts (e.g., docs.rs) restrict or ignore build script side effects. Keep it lightweight.
If you need custom filenames/sections, use clap_mangen::Man::new(cmd).render(&mut writer) and recurse yourself.

Next steps

Package installers can place pages under /usr/share/man/man1/.
Homebrew formulae can install target/man/*.1 during brew install.
Explore docs: clap on docs.rs and clap_mangen on docs.rs for advanced options.

Your Own Private Internet with Nanocl and WireGuard

leone — Mon, 08 Sep 2025 22:25:06 +0000

Want blazing-fast, ultra-secure access to your private network from anywhere in the world? Tired of relying on third-party VPNs? With WireGuard and Nanocl, you can launch your own VPN server in seconds no advanced sysadmin skills required!

In this guide, you'll learn how to:

Set up a WireGuard VPN server on any Linux machine
Use Docker and Nanocl for easy, reliable deployment
Securely connect to your internal services from anywhere

Let's get started and take control of your privacy!

Why Nanocl?

Nanocl turns your server into a "private internet" platform:

Unified internal DNS: services get resolvable names (e.g., my-domain.internal) that your VPN clients can use.
Simple service deployments: reproducible Statefiles define containers, DNS rules, and proxying.
Private-by-default networking: internal services stay reachable only over the VPN.
Consistent experience: the same DNS and routing for all clients, regardless of where they connect from.

In short, Nanocl + WireGuard gives you a clean way to publish and discover internal services securely, with minimal ops overhead.

Prerequisites

A Linux server with a public IP address
- This server will host your WireGuard VPN and be your secure gateway.
Docker installed
- Docker lets you run services in isolated containers.
Nanocl installed
- Nanocl makes container orchestration simple and comes with a built-in proxy and DNS server.

Install Docker

Follow the official Docker installation guide for your Linux distribution. It's quick and easy!

Install Nanocl

Download and install the Nanocl CLI binary with this simple command:

curl -fsSL https://download.next-hat.com/scripts/get-nanocl.sh | sh

Then create a Nanocl group and install Nanocl's internal services:

sudo groupadd nanocl
sudo usermod -aG nanocl $USER
newgrp nanocl
nanocl install

Deploy WireGuard (Your Private VPN)

Now for the fun part! We'll use the popular linuxserver/wireguard image.

A preconfigured Statefile is available on our nanocl repository

It retrieves the users you want to create from environment variables.
You can create a .env file with the following content:

WG_USERS=myuser

You can add multiple users separated by commas:

WG_USERS=user1,user2,user3

And then apply the remote file with:

nanocl state apply -s https://nr.next-hat.com/v0.17/wireguard.yml

Or apply it directly with:

WG_USERS=myuser nanocl state apply -s https://nr.next-hat.com/v0.17/wireguard.yml

The content of the file is as follows:

ApiVersion: v0.17

Args:
- Name: namespace
  Kind: String
  Default: wireguard
- Name: puid
  Kind: String
  Default: 1000
- Name: pgid
  Kind: String
  Default: 1000
- Name: dns
  Kind: String
  Default: "1.1.1.1"
- Name: config-path
  Kind: String
  Default: /opt/containers/wireguard

Namespace: ${{ Args.namespace }}

Cargoes:
- Name: wgsrv
  Container:
    Image: lscr.io/linuxserver/wireguard:latest
    Cmd:
    - -c
    - SERVERURL=$NANOCL_NODE_ADDR sh /init
    Env:
    - PUID=${{ Args.puid }}
    - PGID=${{ Args.pgid }}
    # Set this to your desired users, they will be created automatically
    # When the container start
    # You can add multiple users separated by comma
    - PEERS=${{ Envs.WG_USERS }}
    - PERSISTENTKEEPALIVE_PEERS=all
    HostConfig:
      PortBindings:
        51820/udp:
        - HostPort: "51820"
      CapAdd:
      - NET_ADMIN
      Dns:
      # nanocl will replace this $$INTERNAL_GATEWAY variable
      # with the internal gateway ip
      # which will allow wireguard to resolve internal services
      # registered by nanocl internal dns
      - $$INTERNAL_GATEWAY
      - ${{ Args.dns }}
      Binds:
      -  ${{ Args.config-path }}/config:/config
      Sysctls:
        net.ipv4.ip_forward: "1"

You can customize the namespace, PUID, PGID, DNS server, and config path by passing them as arguments for example:

WG_USERS=myuser nanocl state apply -s nr.next-hat.com/v0.16/wireguard.yml -- --config-path /my/custom/path --puid 1001 --pgid 1001 --dns 8.8.8.8

To get your WireGuard client config, run:

cat /opt/containers/wireguard/config/myuser/myuser.conf

Sample config:

[Interface]
Address = 10.13.13.2
PrivateKey = 4Kgkxcu27g9s69OSYmSbh6jmvu8kCC8h12XxqrI3uH4=
ListenPort = 51820
DNS = 10.13.13.1

[Peer]
PublicKey = O/xFv4cFdrSok+Ujm9r5J6Laf1PcQv0A4u2T8BWQBQ8=
PresharedKey = ZOKnf2Zp30WVuTYgcFO7M0QH5C0c3/XTYqCevC69vOg=
Endpoint = 92.161.136.52:51820
AllowedIPs = 0.0.0.0/0, ::/0

Use this configuration file to connect to your WireGuard server from any device (Windows, Mac, Linux, mobile) using the official WireGuard client.

Deploy internal services

You can now deploy your internal services using Nanocl. They will be accessible through the WireGuard VPN.

For example, we will deploy a simple service that returns HTTP headers.

ApiVersion: v0.17

Namespace: global

Cargoes:
- Name: deploy-example
  Container:
    Image: ghcr.io/next-hat/nanocl-get-started:latest
    Env:
    - APP=EXAMPLE

Resources:
- Name: dns.my-domain.internal
  Kind: ncdns.io/rule
  Data:
    Network: Internal
    Entries:
    - Name: my-domain.internal
      IpAddress: Internal

- Name: my-domain.internal
  Kind: ncproxy.io/rule
  Data:
    Rules:
    - Domain: my-domain.internal
      Network: Internal
      Locations:
      - Path: /
        Target:
          Key: deploy-example.global.c
          Port: 9000

Once connected to your VPN you can now browse
http://my-domain.internal

Security Best Practices

Restrict UDP port 51820 to trusted IPs using your firewall.
Keep your private keys secret never share them!
Regularly update Docker, Nanocl, and WireGuard images.
Monitor server logs for suspicious activity.

Troubleshooting Tips

If the WireGuard container won't start, check Nanocl logs for errors.
Make sure your firewall allows UDP traffic on port 51820.
Verify the config path exists and is writable.
Use nanocl ps and nanocl cargo -n your_namespace list to check running instances.

Visualize Your Setup

Next Steps & Call to Action

You did it! You now have your own high-performance VPN server. Share this guide with friends, tweet your success, and help others take control of their privacy!

Have questions or want to show off your setup? Drop a comment below or tag me on social media!

Basic http proxy in rust with ntex

leone — Fri, 05 Sep 2025 17:21:45 +0000

What is ntex ?

Ntex is a powerful, pragmatic, and extremely fast framework for composable networking services for Rust.
It's one of the fastest web frameworks available in Rust, and provides powerful abstractions for web server development.

Why ntex ?

This are my top reasons for using ntex:

Performance: Ntex is one of the fastest web frameworks available in Rust.
Ergonomic: Ntex provides powerful abstractions for web server development.
Composable: Ntex is designed to be composable, allowing you to build complex web servers from simple components.
Ecosystem: Ntex has a rich ecosystem of middleware, extensions and libraries.
Built-in http client: Ntex provides a built-in http client for making requests to other servers.
Runtime: Ntex allow you to choose between different runtimes, including tokio and async-std.

Setting up the project

Let's start by creating a new project with cargo:

cargo new ntex-http-proxy
cd ntex-http-proxy

Add ntex as dependency:

cargo add ntex --features tokio

Starting with a basic http handler

Let's start by creating a basic http handler that will return Hello, World! in plain text format:

use ntex::{http, web};

async fn forward() -> Result<web::HttpResponse, web::Error> {
  Ok(
    web::HttpResponse::Ok()
      .content_type("text/plain")
      .body("Hello, world!"),
  )
}

#[ntex::main]
async fn main() -> std::io::Result<()> {
  web::server(move || {
    web::App::new()
      .state(http::Client::new())
      .wrap(web::middleware::Logger::default())
      .default_service(web::route().to(forward))
  })
  .bind(("0.0.0.0", 9090))?
  .run()
  .await
}

Let's break down the code:

forward is an async function that returns a web::HttpResponse or a web::Error.
main is the entry point of our application. It's an async function that returns a std::io::Result<()>.
We create a new ntex web server with web::server and pass a closure that returns a web::App.
We create a new http::Client and add it to the app state.
We add a logger middleware to the app.
We define a default service that will forward all requests to the forward handler.
We bind the server to 0.0.0.0:9090 and run it.

Let's test the server by running it:

cargo run
curl http://localhost:9090

You should see Hello, world! in the response.

Adding a proxy handler

We start by adding the url and futures_util crates to our dependencies to be able to parse urls and convert responses to streams:

cargo add url futures-util

Then we change the the code to forward requests to another server:

use futures_util::TryStreamExt;
use ntex::{http, web};

async fn forward(
  req: web::HttpRequest,
  body: ntex::util::Bytes,
  client: web::types::State<http::Client>,
  forward_url: web::types::State<url::Url>,
) -> Result<web::HttpResponse, web::Error> {
  let mut new_url = forward_url.get_ref().clone();
  new_url.set_path(req.uri().path());
  new_url.set_query(req.uri().query());
  let forwarded_req = client.request_from(new_url.as_str(), req.head());
  let res = forwarded_req
    .send_body(body)
    .await
    .map_err(web::Error::from)?;
  let mut client_resp = web::HttpResponse::build(res.status());
  let stream = res.into_stream();
  Ok(client_resp.streaming(stream))
}

#[ntex::main]
async fn main() -> std::io::Result<()> {
  let forward_url = "https://www.rust-lang.org".to_owned();
  let forward_url = url::Url::parse(&forward_url)
    .map_err(|err| std::io::Error::new(std::io::ErrorKind::InvalidData, err))?;
  web::server(move || {
    web::App::new()
      .state(http::Client::new())
      .state(forward_url.clone())
      .wrap(web::middleware::Logger::default())
      .default_service(web::route().to(forward))
  })
  .bind(("0.0.0.0", 9090))?
  .run()
  .await
}

Let's break down the code:

We add the url and futures_util crates to our dependencies.
We change the forward function to take the request, body, client and forward_url as arguments.
We create a new url by cloning the forward_url and setting the path and query from the request.
We create a new request using the client and the new url.
We send the body of the request and await the response.
We build a new response with the status code of the response.
We convert the response into a stream and return it.

Let's test the server by running it:

cargo run
curl http://localhost:9090

You should see the rust-lang.org homepage in the response.

Conclusion

In this tutorial, we created a basic http proxy server using ntex. We started by creating a simple http handler that returns Hello, World! in plain text format. Then we added a proxy handler that forwards requests to another server. We used the url and futures_util crates to parse urls and convert responses to streams. We tested the server by running it and making a request to it. We saw that the server successfully forwarded the request to the target server and returned the response.
We have little to no code to write a basic http proxy server (less than 50 lines of code) and we can easily extend it with more features like caching, rate limiting, authentication, etc.

I hope you enjoyed this tutorial and found it useful. If you have any questions or feedback, feel free to leave a comment below.

Automating deployment with GitHub Actions and Nanocl

leone — Fri, 05 Sep 2025 17:18:48 +0000

Learn how to automate your deployment with GitHub Actions and Nanocl. This guide walks you through setting up seamless deployments, making it easier to deploy your applications with minimal effort. Whether you're new to CI/CD or an experienced developer, this post will show you how to streamline your workflow using powerful open-source tools.

Introduction

Continuous Integration and Continuous Deployment (CI/CD) are essential practices in modern software development. They help automate the process of building, testing, and deploying applications, making it easier to deliver high-quality software quickly and efficiently. GitHub Actions is a powerful tool that allows you to automate your CI/CD pipeline directly from your GitHub repository. Nanocl is a containers and virtual machine orchestrator that simplifies the deployment process by providing a unified interface for managing your infrastructure.

In this blog i will showcase how i did setup our CI/CD pipeline with Github Actions and Nanocl for the deployment of next-hat and and ntex.rs documentation that use docusaurus.

Prerequisites

Before we get started you need a few things:

A GitHub account (you can sign up for free at github.com)
A project to deploy (it can be a static website, a web application, or anything that can run in a container)
A dedicated server or a VPS (i use ovh for servers)
A domain name that point to your server (i use ovh for domain names)
Docker installed on your local machine and server (you can find the installation instructions here)
Nanocl installed on your server (you can find the installation instructions here)

Creating the container image

We will take a look on how to create the container image for the deployment of the documentation of next-hat and ntex.rs that use docusaurus. If you already know how to setup a docker container image you can skip this section.

Creating a Nginx Configuration File

We use nginx as a web server to serve the static files generated by docusaurus. The server.nginx file contains the configuration for the nginx server. You can replace it with your own configuration file to match your use case.

server {
  listen       80;
  listen  [::]:80;
  rewrite ^/(.*)/$ /$1 permanent;

  gzip on;
  gzip_vary on;
  gzip_proxied any;
  gzip_comp_level 8;
  gunzip on;
  gzip_types application/javascript image/* text/css;
  gzip_disable "MSIE [1-6]\.";

  root /home/node/app;
  error_page 404 /404.html;
  try_files $uri.html $uri/index.html =404;

  ## All static files will be cached.
  location ~* ^.+\.(?:css|webp|cur|js|jpe?g|gif|htc|ico|png|html|xml|otf|ttf|eot|woff|woff2|svg)$ {
    access_log off;
    expires 1y;
    add_header Cache-Control max-age=31536000;

    ## No need to bleed constant updates. Send the all shebang in one
    ## fell swoop.
    tcp_nodelay off;

    ## Set the OS file cache.
    open_file_cache max=3000 inactive=120s;
    open_file_cache_valid 45s;
    open_file_cache_min_uses 2;
    open_file_cache_errors off;
  }
}

Let's break down the server.nginx configuration file:

server { ... }: This block defines the configuration for the Nginx server.
listen 80;: This line specifies that the server should listen on port 80.
rewrite ^/(.*)/$ /$1 permanent;: This line redirects requests with a trailing slash to the same URL without the slash.
gzip on;: This line enables gzip compression for responses.
root /home/node/app;: This line specifies the root directory for serving static files.
error_page 404 /404.html;: This line specifies the error page to use for 404 errors.
try_files $uri.html $uri/index.html =404;: This line specifies the files to try when a request is made.
location ~* ^.+\.(?:css|webp|cur|js|jpe?g|gif|htc|ico|png|html|xml|otf|ttf|eot|woff|woff2|svg)$ { ... }: This block specifies the configuration for serving static files with caching enabled.

This configuration file optimizes the Nginx server for serving static files and improves performance by enabling gzip compression and caching.

Creating a Dockerfile

A Dockerfile is a text document that contains all the commands needed to build a Docker image. It specifies the base image to use, the commands to run, and the files to copy into the image. In this guide, we will create a Dockerfile for a docusaurus website. You can replace the commands with the ones needed for your project.

Create a new file in your project directory called Dockerfile. This file will contain the configuration for your Docker image. Here is an example Dockerfile for a docusaurus website:

FROM node:22.11.0-alpine AS builder

RUN apk add git

USER node

# Create app directory (with user `node`)
RUN mkdir -p /home/node/app
# Set is as cwd
WORKDIR /home/node/app

# Install app dependencies
# A wildcard is used to ensure both package.json AND package-lock.json are copied
# where available (npm@5+)
COPY --chown=node package*.json ./

# Install dependencies
RUN npm install

# Bundle app source code
COPY --chown=node . .
COPY --chown=node ./.git ./.git

RUN npm run build

FROM nginx:1.27.0-alpine3.19-slim

WORKDIR /etc/nginx/conf.d

COPY --from=builder /home/node/app/build /home/node/app

COPY ./server.nginx ./default.conf

Let's break down the Dockerfile:

FROM node:22.11.0-alpine AS builder: This line specifies the base image to use for the build stage. We use the node:22.11.0-alpine image, which is a lightweight version of Node.js that includes npm.
RUN apk add git: This line installs the git package, which is needed to clone the repository.
USER node: This line switches to the node user, which is a non-root user created by the Node.js image.
RUN mkdir -p /home/node/app: This line creates a directory for the application code.
WORKDIR /home/node/app: This line sets the working directory to the application directory.
COPY --chown=node package*.json .: This line copies the package.json and package-lock.json files into the image.
RUN npm install: This line installs the dependencies specified in the package.json file.
COPY --chown=node . .: This line copies the application code into the image.
COPY --chown=node ./.git ./.git: This line copies the .git directory into the image.
RUN npm run build: This line builds the application using the npm run build command.
FROM nginx:1.27.0-alpine3.19-slim: This line specifies the base image to use for the final image. We use the nginx:1.27.0-alpine3.19-slim image, which is a lightweight version of Nginx.
WORKDIR /etc/nginx/conf.d: This line sets the working directory to the Nginx configuration directory.
COPY --from=builder /home/node/app/build /home/node/app: This line copies the static files generated by the build stage into the Nginx configuration directory.
COPY ./server.nginx ./default.conf: This line copies the server.nginx file into the Nginx configuration directory.

This Dockerfile creates a multi-stage build that first builds the application using Node.js and then copies the static files into an Nginx image. This approach reduces the size of the final image and improves performance by separating the build dependencies from the runtime dependencies.

Building and Running the Docker Image Locally

Before deploying your application to your server, you should test the Docker image locally to ensure that it works as expected. You can build and run the Docker image on your local machine using the following commands:

docker build -t my-image .
docker run -p 8080:80 my-image

The docker build command builds the Docker image using the Dockerfile in the current directory and tags it with the name my-image. The docker run command runs the Docker image on port 8080, mapping it to port 80 inside the container. You can access the application by opening a web browser and navigating to http://localhost:8080.

If everything works as expected, you should see a production version of your docusaurus website running in the browser. You can now proceed to deploy your application to your server using GitHub Actions and Nanocl.

Setting up Nanocl

Nanocl is a powerful tool that simplifies the deployment process by providing a unified interface for managing your infrastructure. You can use Nanocl to deploy your applications to your server with minimal effort. In this guide, we will show you how to set up Nanocl on your server and deploy your application using a simple configuration file.

First, you need to install Nanocl on your server. You can find the installation instructions here. Once you have installed Nanocl, you can create a configuration file for your application. This file will contain the settings for your application, such as the image name, port number, and environment variables.

By default once installed Nanocl is only accessible via /run/nanocl/nanocl.sock. You can use a proxy rule to expose it to the public internet, however, exposing it to the public without a self signed SSL/TLS certificate is not recommended.
It could allow an attacker to take control of your server.
Hopefully, we have a pre-configured rule that you can apply to expose the Nanocl Daemon.

On your dedicated server or VPS, run the following command to apply the rule:

nanocl state apply -fs https://nr.next-hat.com/v0.16/sys/enable-remote-nanocld.yml

It will expose the Nanocl Daemon to the public internet with a self signed SSL/TLS certificate on the port 9943.

Setting up Github Secrets

GitHub Secrets allow you to securely store and use sensitive information in your GitHub repository. You can use GitHub Secrets to store your server credentials, API keys, and other sensitive information needed to deploy your application. In this guide, we will use GitHub Secrets to store the credentials needed to deploy your application to your server using Nanocl.

To get started, go to your GitHub repository and click on the Settings tab. Then, click on the Secrets and variables link in the left sidebar. Click on the Actions link.

You should see a page like this:

Click on the New repository secret button to create a new secret. You can create a secret for each of the following values:

NANOCL_HOST: The hostname or IP address of your server with the 9943 port. Example: https://example.com:9943
NANOCL_CERT: The content of the self signed SSL/TLS certificate used to secure the connection to the Nanocl Daemon.
NANOCL_CERT_KEY: The content of the private key used to secure the connection to the Nanocl Daemon.

You can find the content of the certificate and private key by running the following commands on your server:

nanocl secret inspect cert.client.nanocl.io

This command will output the content of the certificate and private key. You can copy and paste the content into the GitHub Secrets page.

Creating a Statefile Configuration

A Statefile is a configuration file that contains the settings for your application. It specifies the image name, port number, and environment variables needed to deploy your application. You can create a Statefile for your application and use it to deploy your application to your server using Nanocl.
This is the Statefile i use for the deployment of the next-hat documentation:

ApiVersion: v0.16

Args:
- Name: version
  Kind: String

Cargoes:
- Name: nh-doc
  Container:
    Image: ghcr.io/next-hat/documentation:${{ Args.version }}

Resources:
- Name: http.docs.next-hat.com
  Kind: ncproxy.io/rule
  Data:
    Rules:
    - Domain: docs.next-hat.com
      Network: Public
      # Secret created for the certbot job below
      # You can remove this line if you don't want https
      Ssl: cert.docs.next-hat.com
      Locations:
      - Path: /
        Target:
          Key: nh-doc.global.c
          Port: 80
    - Domain: docs.next-hat.com
      Network: Public
      Locations:
      - Path: /
        Target:
          Url: https://docs.next-hat.com
          Redirect: Temporary

This Statefile must be placed in the root of your project directory.

Setting up GitHub Actions

GitHub Actions allow you to automate your workflow directly from your GitHub repository. You can create custom workflows that run on specific events, such as pushing code to your repository or creating a pull request. In this guide, we will create a workflow that builds and deploys your application to your server using Nanocl.
You can find the full source code here

Building and Publishing the Docker Image

To get started, create a new file in your repository called .github/workflows/build-and-publish.yml. This file will contain the configuration for your GitHub Actions workflow. And will be used to build your docker image and publish it to github container registry. Only when we are merging to master branch.

name: Build and publish docker image

on:
  push:
    branches:
      - master

jobs:
  deploy:
    name: Build and publish docker image
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

      - name: Log in to GitHub Container Registry
        uses: docker/login-action@v2
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract version from package.json
        id: extract_version
        run: |
          version=$(jq -r '.version' package.json)
          echo "PACKAGE_VERSION=$version" >> $GITHUB_ENV

      - name: Check if version already exists
        id: check_version
        run: |
          VERSION=${{ env.PACKAGE_VERSION }}
          IMAGE_NAME=ghcr.io/${{ github.repository_owner }}/my-image
          if docker manifest inspect $IMAGE_NAME:$VERSION > /dev/null 2>&1; then
            echo "Version $VERSION already exists."
            exit 1
          fi
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: |
            ghcr.io/${{ github.repository_owner }}/documentation:latest
            ghcr.io/${{ github.repository_owner }}/documentation:${{ env.PACKAGE_VERSION }}

This workflow will run every time you merge code in the master branch of your repository. It will build a docker image from your code, tag it with the latest version from your package.json file, and push it to the GitHub Container Registry. You can replace documentation with your image name.

Deploying the Application with Nanocl

Next, create a new file in your repository called .github/workflows/deploy.yml. This file will contain the configuration for your GitHub Actions workflow. And will be used to deploy your application to your server using Nanocl.

name: Deploy

on:
  workflow_run:
    workflows: ["Build and publish Docker image"]
    types:
      - completed

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout repository
      uses: actions/checkout@v3

    - name: Install nanocl cli
      run: |
        wget https://github.com/next-hat/nanocl/releases/download/nanocl-0.16.2/nanocl_0.16.2_amd64.deb
        sudo dpkg -i nanocl_0.16.2_amd64.deb
        rm nanocl_0.16.2_amd64.deb

    - name: Deploy to production
      run: |
        VERSION=$(jq -r '.version' package.json)
        nanocl version
        echo $VERSION
        nanocl state apply -ys Statefile.yml -- --version $VERSION
      env:
        HOST: ${{ secrets.NANOCL_HOST }}
        CERT: ${{ secrets.NANOCL_CERT }}
        CERT_KEY: ${{ secrets.NANOCL_CERT_KEY }}

This workflow will run every time the Build and publish Docker image workflow is completed. It will deploy your application to your server using Nanocl. You can replace Statefile.yml with the path to your Statefile configuration file if you have a different name of path.

Now you have set up your CI/CD pipeline with GitHub Actions and Nanocl. Every time you push code to your repository, GitHub Actions will build and publish your Docker image to the GitHub Container Registry. Once the image is published, it will trigger the deployment workflow, which will deploy your application to your server using Nanocl.

Enable public SSL/TLS with Let's Encrypt

Additionally you can enable public SSL/TLS with Let's Encrypt. You can use the following command to enable public SSL/TLS with Let's Encrypt:

nanocl state apply -fs https://nr.next-hat.com/v0.16/sys/certbot.yml -- --email contact@next-hat.com --domain docs.next-hat.com

Conclusion

By following the steps outlined in this guide, you can automate the deployment of your applications to your server with minimal effort and zero downtime. This will help you deliver high-quality software quickly and efficiently, making it easier to manage your infrastructure and deploy your applications with confidence.

Now that you know how to automate your deployment with GitHub Actions and Nanocl, why not give it a try with your own project? Let us know how it goes or if you have any questions!

You can join my discord server if you have any questions or need help with setting up your CI/CD pipeline with GitHub Actions and Nanocl. I'm here to help you succeed in your software development journey.

Solving the Localhost Development Headache with Nanocl

leone — Thu, 04 Sep 2025 19:39:20 +0000

Developers often face significant challenges when working on projects locally, especially when it comes to managing multiple services, dealing with CORS and cookies, and ensuring that the development environment mirrors production. However, there's a promising solution on the horizon: Nanocl.

Introducing Nanocl

Nanocl is a powerful tool designed to streamline project deployment and alleviate the pains associated with localhost development. By seamlessly integrating with your development workflow, Nanocl simplifies the process of running multiple services locally and eliminates common headaches like CORS issues, port conflicts and cookies.

The Problem at Hand

Consider a scenario where you're working on a project consisting of various components—an API, a dashboard, and a login page. Traditionally, you would need to run each of these components on different ports, leading to cumbersome setups and potential conflicts. Additionally, issues like CORS and cookies become apparent, especially when these services aren't bound to a specific domain. Managing these challenges manually can be time-consuming and error-prone, detracting from your productivity and focus on actual development tasks.

How Nanocl Comes to the Rescue

Nanocl provides a comprehensive solution to the localhost development headache. By leveraging its powerful features, developers can streamline their workflow and focus on building great software without getting bogged down by infrastructure complexities.

Seamless Integration

Nanocl seamlessly integrates with your existing development environment, allowing you to deploy your project with a single command. Gone are the days of juggling multiple terminals and wrestling with configuration files—Nanocl handles it all for you.

Domain Resolution

One of Nanocl's standout features is its ability to create domains for your local machine, bringing your development environment closer to production. With Nanocl, you can access your services using intuitive domain names like api.dev.internal, console.dev.internal, and auth.dev.internal, making testing and debugging a breeze.

Realistic Testing Environment

By replicating the production setup locally, Nanocl enables developers to test their projects in a more realistic environment. This ensures smoother transitions from development to production and reduces the likelihood of encountering unforeseen issues down the line.

Getting Started with Nanocl

Ready to kiss localhost headaches goodbye? Here's how to get started with Nanocl:

Installation: Refer to the Nanocl documentation for detailed instructions on installing Nanocl on your machine.
Clone the Example Repository: Once Nanocl is installed, clone the example repository provided to see Nanocl in action.
```
git clone https://github.com/0xle0ne/solving-localhost-dev
```
Run the Project: Navigate to the cloned repository and run the project using Nanocl.
```
cd solving-localhost-dev
nanocl state apply -fs Statefile.yml
```
Update /etc/resolve.conf: Retrieve the IP address of the DNS server by running the following command:
```
nanocl namespace ls
```
The output will display the IP address of the DNS server, which you'll need to add to your /etc/resolve.conf file.
```
NAME      CARGOES    INSTANCES    GATEWAY     CREATED AT
system    7          7            10.1.0.1    2024-05-09 15:52:27
global    4          4            10.2.0.1    2024-05-09 15:52:27
```
Update your /etc/resolve.conf file with the IP address of the gateway:
```
nameserver <global-namespace-gateway-ip>
```
Access Your Domains: Once the setup is complete, you can access your services using the designated domains (api.dev.internal, console.dev.internal, auth.dev.internal). Enjoy a headache-free development experience!

How it works

Nanocl will parse the Statefile.yml to know the current state of the services. It will then create the necessary namespaces, cargoes, and instances to run the services. The services will be available at the domains specified in the Statefile.yml.

With a combinaison of a DNS server and a reverse proxy, Nanocl will resolve the domains to the correct services.

Key Takeaways

Simplified Development Workflow: Nanocl streamlines the process of running multiple services locally, enabling developers to focus on building great software.
Domain Resolution: Nanocl help you to setup intuitive domains for your services, making it easier to test and debug your projects.
Realistic Testing Environment: By mirroring the production setup locally, Nanocl helps developers identify and resolve issues early on, leading to smoother deployments.
Seamless Integration: Nanocl seamlessly integrates with your existing development environment, eliminating the need for manual configurations and complex setups.

Conclusion

With Nanocl, localhost development doesn't have to be a headache anymore. By providing a seamless solution to common challenges, Nanocl empowers developers to focus on what they do best—building innovative software. Say goodbye to CORS woes, port conflicts and cookies problems, and hello to a smoother, more efficient development workflow. Give Nanocl a try today and unlock a world of possibilities for your projects. Happy coding!

REST API in RUST with ntex

leone — Wed, 03 Sep 2025 07:38:17 +0000

Hey, today I wanted to share my knowledge on how to write a Rest API in Rust. It may be easier than you think!
We won't showcase database connectivity in this article. Instead, we focused on demonstrating how to generate OpenAPI specifications and serve a Swagger UI.

You can find the full code source on github.

Before starting, make sure you have Rust installed.

Let's start by initializing a new project using cargo init.

cargo init my-rest-api
cd my-rest-api

That should produce the following directory structure:

├── Cargo.toml
└── src
    └── main.rs

You can use rustfmt for formatting. To do so, create a rustfmt.toml file with the following content:

indent_style = "Block"
max_width = 80
tab_spaces = 2
reorder_imports = false
reorder_modules = false
force_multiline_blocks = true
brace_style = "PreferSameLine"
control_brace_style = "AlwaysSameLine"

I personally use VSCode. Optionally, you can add this configuration in your .vscode/settings.json:

{
  "editor.rulers": [80],
  "editor.tabSize": 2,
  "editor.detectIndentation": false,
  "editor.trimAutoWhitespace": true,
  "editor.formatOnSave": true,
  "files.insertFinalNewline": true,
  "files.trimTrailingWhitespace": true,
  "rust-analyzer.showUnlinkedFileNotification": false,
  "rust-analyzer.checkOnSave": true,
  "rust-analyzer.check.command": "clippy"
}

Your new directory structure should look like this:

├── .gitignore
├── .vscode
│   └── settings.json
├── Cargo.lock
├── Cargo.toml
├── rustfmt.toml
└── src
    └── main.rs

We are going to use ntex as our HTTP framework.

We can install Rust dependencies by running cargo add.

Note that when using ntex, we have the ability to choose our runtime.

To quickly summarize, the runtime will manage your async|await pattern.

If you are familiar with the nodejs runtime, it's kind of similar in usage.

For this tutorial, we are going to use tokio as it seems to be the more popular choice. Let's add ntex as a dependency:

cargo add ntex --features tokio

Then we are going to update our main.rs file with the following content:

use ntex::web;

#[web::get("/")]
async fn index() -> &'static str {
  "Hello world!"
}

#[ntex::main]
async fn main() -> std::io::Result<()> {
  web::server(|| web::App::new().service(index))
    .bind(("0.0.0.0", 8080))?
    .run()
    .await?;
  Ok(())
}

We can run our project by using the following command:

cargo run

This command will compile our code and run it.

You should see the following output:

Finished dev [unoptimized + debuginfo] target(s) in 17.38s
Running `target/debug/my-rest-api`

We can test our server using curl:

curl -v localhost:8080

*   Trying 127.0.0.1:8080...
* TCP_NODELAY set
* Connected to localhost (127.0.0.1) port 8080 (#0)
> GET / HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.68.0
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< content-length: 12
< content-type: text/plain; charset=utf-8
< date: Fri, 26 May 2023 11:43:01 GMT
<
* Connection #0 to host localhost left intact
Hello world!%

Congratulations! You now have your first HTTP server in Rust!

Now let's create our first REST endpoints.

Regarding the directory architecture, it's up to personal preference. In ntex, we use the .service() method to add new endpoints. Therefore, I have chosen to create a directory called services to house my endpoints.

Let's create the directory:

mkdir src/services
touch src/services/mod.rs

Note that by default, Rust tries to import a mod.rs file from our directories.

Let's create our default endpoints inside services/mod.rs:

use ntex::web;

pub async fn default() -> web::HttpResponse {
  web::HttpResponse::NotFound().finish()
}

Now we need to indicate that we want to use this module in our main.rs:

use ntex::web;

mod services;

#[ntex::main]
async fn main() -> std::io::Result<()> {
  web::server(|| {
    web::App::new()
      // Default endpoint for unregisterd endpoints
      .default_service(web::route().to(services::default)
    )
  })
  .bind(("0.0.0.0", 8080))?
  .run()
  .await?;
  Ok(())
}

Now, for any unregistered endpoints, we will have a 404 error.

Before continuing, let's add four dependencies: serde and serde_json for JSON serialization, and utoipa with utoipa-swagger-ui to have an OpenAPI swagger.

cargo add serde --features derive
cargo add serde_json utoipa utoipa-swagger-ui

Next, we are going to create our own HttpError type as helpers. Create a file under src/error.rs with the following content:

use ntex::web;
use ntex::http;
use utoipa::ToSchema;
use serde::{Serialize, Deserialize};

/// An http error response
#[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
pub struct HttpError {
  /// The error message
  pub msg: String,
  /// The http status code, skipped in serialization
  #[serde(skip)]
  pub status: http::StatusCode,
}

/// Helper function to display an HttpError
impl std::fmt::Display for HttpError {
  fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
    write!(f, "[{}] {}", self.status, self.msg)
  }
}

/// Implement standard error for HttpError
impl std::error::Error for HttpError {}

/// Helper function to convert an HttpError into a ntex::web::HttpResponse
impl web::WebResponseError for HttpError {
  fn error_response(&self, _: &web::HttpRequest) -> web::HttpResponse {
    web::HttpResponse::build(self.status).json(&self)
  }
}

We need to import our error module in our main.rs let update it:

use ntex::web;

mod error;
mod services;

#[ntex::main]
async fn main() -> std::io::Result<()> {
  web::server(|| {
    web::App::new()
      // Default endpoint for unregisterd endpoints
      .default_service(web::route().to(services::default)
    )
  })
  .bind(("0.0.0.0", 8080))?
  .run()
  .await?;
  Ok(())
}

I think we are ready to write some example endpoints. Let's simulate a todo list and create a new file under src/services/todo.rs:

use ntex::web;

#[web::get("/todos")]
pub async fn get_todos() -> web::HttpResponse {
  web::HttpResponse::Ok().finish()
}

#[web::post("/todos")]
pub async fn create_todo() -> web::HttpResponse {
  web::HttpResponse::Created().finish()
}

#[web::get("/todos/{id}")]
pub async fn get_todo() -> web::HttpResponse {
  web::HttpResponse::Ok().finish()
}

#[web::put("/todos/{id}")]
pub async fn update_todo() -> web::HttpResponse {
  web::HttpResponse::Ok().finish()
}

#[web::delete("/todos/{id}")]
pub async fn delete_todo() -> web::HttpResponse {
  web::HttpResponse::Ok().finish()
}

pub fn ntex_config(cfg: &mut web::ServiceConfig) {
  cfg.service(get_todos);
  cfg.service(create_todo);
  cfg.service(get_todo);
  cfg.service(update_todo);
  cfg.service(delete_todo);
}

We need to update our src/services/mod.rs to import our todo.rs:

pub mod todo;

use ntex::web;

pub async fn default() -> web::HttpResponse {
  web::HttpResponse::NotFound().finish()
}

In our main.rs:

use ntex::web;

mod error;
mod services;

#[ntex::main]
async fn main() -> std::io::Result<()> {
  web::server(|| {
    web::App::new()
      // Register todo endpoints
      .configure(services::todo::ntex_config)
      // Default endpoint for unregisterd endpoints
      .default_service(web::route().to(services::default))
  })
  .bind(("0.0.0.0", 8080))?
  .run()
  .await?;
  Ok(())
}

Let's create some data structure for our Todo.
We are going to create a new directory src/models with his mod.rs and a todo.rs

mkdir src/models
touch src/models/mod.rs
touch src/models/todo.rs

In our src/models/mod.rs we are going to import todo.rs:

pub mod todo;

And inside src/models/todo.rs, we are going to add some data structure:

use utoipa::ToSchema;
use serde::{Serialize, Deserialize};

/// Todo model
#[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
pub struct Todo {
  /// The todo id
  pub id: i32,
  /// The todo title
  pub title: String,
  /// The todo completed status
  pub completed: bool,
}

/// Partial Todo model
#[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
pub struct TodoPartial {
  /// The todo title
  pub title: String,
}

You may notice that we use the serde and utoipa derive macros to enable JSON serialization and conversion to OpenAPI Schema.

Don't forget to update your main.rs to import our models:

use ntex::web;

mod error;
mod models;
mod services;

#[ntex::main]
async fn main() -> std::io::Result<()> {
  web::server(|| {
    web::App::new()
      // Register todo endpoints
      .configure(services::todo::ntex_config)
      // Default endpoint for unregisterd endpoints
      .default_service(web::route().to(services::default))
  })
  .bind(("0.0.0.0", 8080))?
  .run()
  .await?;
  Ok(())
}

With the models in place, we can now generate type-safe endpoints with their documentation. Let's update our endpoints inside src/services/todo.rs:

use ntex::web;

use crate::models::todo::TodoPartial;

/// List all todos
#[utoipa::path(
  get,
  path = "/todos",
  responses(
    (status = 200, description = "List of Todo", body = [Todo]),
  ),
)]
#[web::get("/todos")]
pub async fn get_todos() -> web::HttpResponse {
  web::HttpResponse::Ok().finish()
}

/// Create a new todo
#[utoipa::path(
  post,
  path = "/todos",
  request_body = TodoPartial,
  responses(
    (status = 201, description = "Todo created", body = Todo),
  ),
)]
#[web::post("/todos")]
pub async fn create_todo(
  _todo: web::types::Json<TodoPartial>,
) -> web::HttpResponse {
  web::HttpResponse::Created().finish()
}

/// Get a todo by id
#[utoipa::path(
  get,
  path = "/todos/{id}",
  responses(
    (status = 200, description = "Todo found", body = Todo),
    (status = 404, description = "Todo not found", body = HttpError),
  ),
)]
#[web::get("/todos/{id}")]
pub async fn get_todo() -> web::HttpResponse {
  web::HttpResponse::Ok().finish()
}

/// Update a todo by id
#[utoipa::path(
  put,
  path = "/todos/{id}",
  request_body = TodoPartial,
  responses(
    (status = 200, description = "Todo updated", body = Todo),
    (status = 404, description = "Todo not found", body = HttpError),
  ),
)]
#[web::put("/todos/{id}")]
pub async fn update_todo() -> web::HttpResponse {
  web::HttpResponse::Ok().finish()
}

/// Delete a todo by id
#[utoipa::path(
  delete,
  path = "/todos/{id}",
  responses(
    (status = 200, description = "Todo deleted", body = Todo),
    (status = 404, description = "Todo not found", body = HttpError),
  ),
)]
#[web::delete("/todos/{id}")]
pub async fn delete_todo() -> web::HttpResponse {
  web::HttpResponse::Ok().finish()
}

pub fn ntex_config(cfg: &mut web::ServiceConfig) {
  cfg.service(get_todos);
  cfg.service(create_todo);
  cfg.service(get_todo);
  cfg.service(update_todo);
  cfg.service(delete_todo);
}

With utoipa, we will be able to serve our Swagger documentation.

Let's create a new file under src/services/openapi.rs:

use std::sync::Arc;

use ntex::web;
use ntex::http;
use ntex::util::Bytes;
use utoipa::OpenApi;

use crate::error::HttpError;
use crate::models::todo::{Todo, TodoPartial};

use super::todo;

/// Main structure to generate OpenAPI documentation
#[derive(OpenApi)]
#[openapi(
  paths(
    todo::get_todos,
    todo::create_todo,
    todo::get_todo,
    todo::update_todo,
    todo::delete_todo,
  ),
  components(schemas(Todo, TodoPartial, HttpError))
)]
pub(crate) struct ApiDoc;

#[web::get("/{tail}*")]
async fn get_swagger(
  tail: web::types::Path<String>,
  openapi_conf: web::types::State<Arc<utoipa_swagger_ui::Config<'static>>>,
) -> Result<web::HttpResponse, HttpError> {
  if tail.as_ref() == "swagger.json" {
    let spec = ApiDoc::openapi().to_json().map_err(|err| HttpError {
      status: http::StatusCode::INTERNAL_SERVER_ERROR,
      msg: format!("Error generating OpenAPI spec: {}", err),
    })?;
    return Ok(
      web::HttpResponse::Ok()
        .content_type("application/json")
        .body(spec),
    );
  }
  let conf = openapi_conf.as_ref().clone();
  match utoipa_swagger_ui::serve(&tail, conf.into()).map_err(|err| {
    HttpError {
      msg: format!("Error serving Swagger UI: {}", err),
      status: http::StatusCode::INTERNAL_SERVER_ERROR,
    }
  })? {
    None => Err(HttpError {
      status: http::StatusCode::NOT_FOUND,
      msg: format!("path not found: {}", tail),
    }),
    Some(file) => Ok({
      let bytes = Bytes::from(file.bytes.to_vec());
      web::HttpResponse::Ok()
        .content_type(file.content_type)
        .body(bytes)
    }),
  }
}

pub fn ntex_config(config: &mut web::ServiceConfig) {
  let swagger_config = Arc::new(
    utoipa_swagger_ui::Config::new(["/explorer/swagger.json"])
      .use_base_layout(),
  );
  config.service(
    web::scope("/explorer/")
      .state(swagger_config)
      .service(get_swagger),
  );
}

Don't forget to update src/services/mod.rs to import src/services/openapi.rs:

pub mod todo;
pub mod openapi;

use ntex::web;

pub async fn default() -> web::HttpResponse {
  web::HttpResponse::NotFound().finish()
}

Then we can update our main.rs to register our explorer endpoints:

use ntex::web;

mod error;
mod models;
mod services;

#[ntex::main]
async fn main() -> std::io::Result<()> {
  web::server(|| {
    web::App::new()
      // Register swagger endpoints
      .configure(services::openapi::ntex_config)
      // Register todo endpoints
      .configure(services::todo::ntex_config)
      // Default endpoint for unregisterd endpoints
      .default_service(web::route().to(services::default))
  })
  .bind(("0.0.0.0", 8080))?
  .run()
  .await?;
  Ok(())
}

We are good to go. Let's run our server:

cargo run

Then we should be able to access to our explorer on http://localhost:8080/explorer/

I Hope you will try to write your next REST API in Rust !

Don't forget to take a look at the dependencies documentation:

Bonus

Create a production docker image !
Add a Dockerfile in your project directory with the following content:

# Builder
FROM rust:1.69.0-alpine3.17 as builder

WORKDIR /app

## Install build dependencies
RUN apk add alpine-sdk musl-dev build-base upx

## Copy source code
COPY Cargo.toml Cargo.lock ./
COPY src ./src

## Build release binary
RUN cargo build --release --target x86_64-unknown-linux-musl
## Pack release binary with UPX (optional)
RUN upx --best --lzma /app/target/x86_64-unknown-linux-musl/release/my-rest-api

# Runtime
FROM scratch

## Copy release binary from builder
COPY --from=builder /app/target/x86_64-unknown-linux-musl/release/my-rest-api /app

ENTRYPOINT ["/app"]

Optionally you can add this release profile in your Cargo.toml:

[profile.release]
opt-level = "z"
codegen-units = 1
strip = true
lto = true

This will optimise the release binary to be as small as possible. Additionally with upx we can create really small docker image !

Build your image:

docker build -t my-rest-api:0.0.1 -f Dockerfile .

If you want to see a more real world usecase i invite you to take a look at my opensource project Nanocl. That try to simplify the development and deployment of micro services, with containers or virtual machines !

Happy coding !

Forem: leone

Build a Fast GeoIP API in Rust with ntex

Why ntex?

Prerequisites

Install dependencies

Create a basic endpoint

Implement the logic

What is an LRU cache and why use it?

Why shard the cache?

Why use Arc for AppState?

Test the service

Optimize for speed

Benchmark the endpoint

Conclusion

Run local LLMs in under 5 minutes using Nanocl

Overview

Stack Components

Prerequisites

1. Docker

2. Nanocl

3. (Optional) Nvidia Container Toolkit

Step 1: Deploy Ollama with Nanocl

Step 2: Deploy Open WebUI with Nanocl

Step 3: Access Open WebUI

1. Create Your Admin Account

2. Download a Model

3. Start Chatting

Resources

Deploy a complete media center on Nanocl

Prerequisites

Step 1 - Create media_center.yml

Step 2 - Apply the state

Step 3 - Enable name resolution for internal domains

Step 4 - Post-deploy configuration

Deluge

Jackett

Radarr

Jellyfin

Sonarr and Lidarr

Bonus - Lock down access with a VPN

Troubleshooting

Disclaimer

References

Deploy Vaultwarden on Nanocl

Prerequisites

Docker

Nanocl

Deploy Vaultwarden

Create a self-signed SSL certificate (basic)

Create a self-signed SSL certificate (advanced)

Apply the Vaultwarden Statefile

Accessing Vaultwarden

Next Steps

Conclusion

How to easily create a CLI in Rust using clap and clap_mangen

What's a "man page" and why care?

Quick setup

Why this is neat

The CLI definition (derive)

Minimal runtime: main.rs

Sharing CLI with build.rs

Generating man pages recursively

How the pieces fit together

Try it locally

Caveats & tradeoffs

Next steps

Your Own Private Internet with Nanocl and WireGuard

Why Nanocl?

Prerequisites

Install Docker

Install Nanocl

Deploy WireGuard (Your Private VPN)

Deploy internal services

Security Best Practices

Troubleshooting Tips

Visualize Your Setup

Next Steps & Call to Action

Basic http proxy in rust with ntex

What is ntex ?

Why ntex ?

Step 1 - Create `media_center.yml`

Minimal runtime: `main.rs`

Sharing CLI with `build.rs`