--- url: /about.md --- # About Ciara is an open-source project distributed under the MIT License. Feel free to contribute by [opening a Pull Request on GitHub](https://github.com/andresribeiro/ciara/pulls). Thank you for using Ciara. --- --- url: /builder.md --- # Builder Ciara builds your application on a remote server. The default build server is the IP address you entered while running `ciara init`. ### Build Architecture If you are deploying on multiple servers, all of them should have the same architecture. This means that all your servers should be either `amd64` or `arm64`. You can't mix both of them. > Ciara detects the architecture of the builder server and creates a build only for this architecture, as [QEMU](https://docs.docker.com/build/building/multi-architecture/#qemu) builds are very slow. ## Custom Builder To configure a custom remote builder server: ::: code-group ````json [ciara.config.json] { "builder": { "host": "94..." // Your server builder IP } } ::: ## Local builder: If you want to build your application on your computer: ::: code-group ```json [ciara.config.json] { "builder": { "host": "local" } } ::: If you are building locally, your server(s) should have the same architecture of your local computer. It means that if your computer is `amd64`, all your servers should also be `amd64`. ```` --- --- url: /README.md --- # Ciara Documentation πŸ“š [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Repo](https://img.shields.io/badge/Main%20Repo-Ciara-blue)](https://github.com/andresribeiro/ciara-docs) Documentation for [Ciara](https://github.com/andresribeiro/ciara) - A tool to securely deploy any application on any server. ## Local Development To run docs locally: ```bash git clone https://github.com/andresribeiro/ciara-docs.git cd ciara-docs bun install bun docs:dev ``` ## Contributing Found a typo or missing information? * Fork this repository * Edit the markdown files * Submit a Pull Request --- --- url: /creating-a-server.md --- # Creating a Server ## Operating System Ciara requires that you use Debian as your Operating System. ## Configuration No prior configuration on your server is required. In fact, we recommend that you provide Ciara a server β€œas is”. In other words, the recommendation is that you create a server and don't modify anything. ## SSH User SSH connections are always made with `root` user as Ciara needs to perform system-level operations. ## SSH Private Key Ciara connects to your server using SSH private keys. Connections via password are not supported and will not be implemented for security reasons. If you have a custom path for your SSH Private Key, you can configure it on `ciara.config.json`: ::: code-group ```json [ciara.config.json] { "ssh": { "privateKeyPath": "/home/users/myuser/.ssh/id_rsa" } } ``` ::: > Ciara disables SSH password logins on your server for enhanced security after a successful connection. ## SSH Port If your server is running SSH on a custom port, you can configure it on `ciara.config.json`: ::: code-group ```json [ciara.config.json] { "servers": [ { "ip": "94...", "port": 1010 // Your custom SSH port } ] } ``` --- --- url: /databases-plugins-add-ons.md --- # Databases/Plugins/Add-ons Ciara currently does not support databases or other accessory services (often referred to as plugins or add-ons). The recommended approach for deploying databases and other services is to connect to your server via SSH and run them using Docker. This provides flexibility and allows you to manage your database instances independently. Below are some basic Docker examples for common databases: ## Postgres ```bash docker run --name my-postgres -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -d --restart always postgres ``` ## MySQL ```bash docker run --name my-mysql -e MYSQL_ROOT_PASSWORD=mysecretpassword -p 3306:3306 -d --restart always mysql ``` ## MongoDB ```bash docker run --name my-mongo -p 27017:27017 -d --restart always mongo ``` ## Redis ```bash docker run --name my-redis -p 6379:6379 -d --restart always redis ``` --- --- url: /deploying.md --- # Deploying No previous configuration on your servers is required. ## Dockerfile Your apps are deployed with Docker, so you should create an Dockerfile at the root of your project. Ciara will use this Dockerfile to build an image and deploy to your servers. ## First deployment All deployment-related configurations are managed within the `ciara.config.json` file located in the root of your project. To make your first deploy, run: ```bash ciara deploy ``` ## Subsequent deployments For deploying a new version of your app, just run: ```bash ciara deploy ``` ## Updating Configurations To update anything on your deployment, modify your `ciara.config.json` and then run: ```bash ciara deploy ``` Ciara will then read your `ciara.config.json` file and automatically execute all necessary steps to update your application based on the new configuration. --- --- url: /environment-variables.md --- # Environment Variables Environment variables for your application are read from a separate file. This file's path is specified in your `ciara.config.json` under the `env` property, as shown below: ::: code-group ```json [ciara.config.json] { "env": "./production.env" } ``` ::: --- --- url: /firewall.md --- # Firewall ## Inbound Ciara drops by default all inbound traffic except for ports `80` (HTTP) and `443` (HTTPS). These ports are always open and this cannot be changed. To allow additional ports, configure them in your `ciara.config.json`: ::: code-group ```json [ciara.config.json] { "firewall": { "inbound": [ { "port": 22, "allow": "*", "protocols": ["tcp"] }, { "port": 3000, "allow": "*", "protocols": ["tcp", "udp"] } ] } } ``` ::: > When you run `ciara init`, a firewall rule is added to allow inbound traffic on port 22 from any IP. If you remove this rule, you might be locked out from your server as you might not be able to connect to it via SSH. ## Restrict to specific IPs > Currently only IPv4 is supported. If you wish to allow traffic only from specific IPs, you can pass an array of IPs for `allow`: ::: code-group ```json [ciara.config.json] { "firewall": { "inbound": [ { "port": 3000, "allow": ["10.0.0.2", "10.0.0.3"], "protocols": ["tcp"] } ] } } ``` ::: ## Outbound Ciara allows all outbound traffic. --- --- url: /healthcheck.md --- # Healthcheck Ciara allows you to configure an healthcheck for your applications to ensure your deployment was successful. You can define it in your `ciara.config.json`: ::: code-group ```json [ciara.config.json] { "healthcheck": { "path": "/health", "interval": 5, "timeout": 3, "retries": 5 } } ``` ::: * `path`: The HTTP path that Ciara will probe to check the application's health. It's a GET request. * `interval`: The time, in seconds, between healthcheck attempts. * `timeout`: The maximum time, in seconds, Ciara will wait for a response from the healthcheck path. * `retries`: The number of consecutive failed healthchecks after which Ciara will consider the application unhealthy and throw a deployment error. --- --- url: /high-availability.md --- # High Availability (HA) Ciara allows you to set up your servers in multiple locations to achieve high availability. To distribute traffic among these servers, you will need to place a load balancer in front of your Ciara deployments. ## Caddy and Downtime Caddy upgrades, the proxy used by Ciara, require brief periods of downtime. When Caddy is upgraded, the proxy will temporarily stop and restart, which can lead to a short interruption in service. --- --- url: /llms.md --- # LLMs We provide [llms-full.txt](/llms-full.txt), an file with our entire docs for your use with LLMs for any question you may have. --- --- url: /multiple-apps.md --- # Multiple Apps Running multiple apps on a single server is not currently supported. --- --- url: /multiple-servers.md --- # Multiple Servers Ciara can deploy your application on `N` servers. There's no limit on how many servers you can use. You can put all these servers behind a Load Balancer if you want to. ## Adding a New Server If you wish to add another server to the pool of servers you have, update `servers` on `ciara.config.json`: ::: code-group ````json [ciara.config.json] { "servers": [ { "ip": "94...", "port": 22 }, { "ip": "162...", "port": 22 } ] } ::: Then run: ```bash ciara deploy ```` Note that all your servers should have the same architecture. Check [Build Architecture](/builder.html#build-architecture) for more details. --- --- url: /proxy.md --- # Proxy/HTTPS ## HTTP Port You should define on which port your app is running: ::: code-group ```json [ciara.config.json] { "proxy": { "port": 3000 } } ``` ::: Ciara's proxy automatically routes external traffic to your app on ports `80` (HTTP) and `443` (HTTPS). By default, HTTP requests will be redirected to HTTPS. ## HTTPS Ciara automates the setup and management of HTTPS/SSL for your applications using [Caddy](https://caddyserver.com/). You don't need to manually configure certificates or worry about their renewal. For Caddy to automatically serve HTTPS for your domain, you must ensure your domain is correctly pointed to your server's IP address. Besides DNS configuration, you need to set your domain on `ciara.config.json`: ::: code-group ```json [ciara.config.json] { "proxy": { "domains": ["example.com"] } } ``` ::: ## Custom Proxy Configuration If you require more advanced Caddy configurations, you can provide a custom [Caddyfile](https://caddyserver.com/docs/caddyfile-tutorial). This file's path is specified in your `ciara.config.json`. This is optional; if not provided, Ciara will generate a Caddyfile for you. ::: code-group ```json [ciara.config.json] { "proxy": { "caddyfile": "./caddyfile" } } ``` ::: If you provide a custom Caddyfile, any other proxy property, like `domains`, will be ignored. You will need to configure these properties directly within your custom Caddyfile. --- --- url: /quickstart.md --- # Quickstart Let's get you deploying with Ciara. ## Installation To use Ciara, you need to have [Bun](https://bun.sh) installed on your system. Once Bun is installed, install the Ciara CLI globally by running: ```bash npm install -g ciara-deploy ``` ## Initializing a project On your project root, run the following command on your terminal: ```bash ciara init ``` **Output** ``` βœ” What is your app name? my-website βœ” What is the IP address of the server? 94... βœ” Which port is your application running on? 3000 βœ” Would you like to set up a domain? Yes βœ” Enter your domain: example.com ciara.config.json created. ``` This command will create an `ciara.config.json` on your project root. We talk more about this file on the next section. --- --- url: /security.md --- # Security ## SSH Please refer to [Creating a Server](/creating-a-server#ssh.html). ## Unattended Upgrades Please refer to [Server Updates](/server-updates.html). ## Fail2ban For enhanced SSH security, Ciara automatically configures Fail2ban on the SSH port. Fail2ban is an intrusion prevention framework that scans log files for malicious activity (like repeated failed login attempts) and automatically bans the offending IP addresses, protecting your server from brute-force attacks. ## Port Exposure By default, Ciara is designed to minimize the attack surface by only exposing essential ports. Ciara drops all inbound traffic, except the ports listed on [Firewall](/firewall#inbound) section. We strongly recommend that you only expose the necessary ports for your applications. ## Cloud Deployments When deploying Ciara on cloud platforms, we recommend setting up a private connection between your servers if the cloud provider offers such a feature. ## Disclaimer While Ciara implements several security features and provides recommendations, no system can guarantee absolute security. Ciara is a deployment tool, and while it aims to facilitate secure deployments, we are not responsible for the overall security posture of your servers or applications. Users are responsible for implementing and maintaining their own security best practices, including regular security audits, vigilant monitoring, and adherence to their organization's security policies. --- --- url: /server-updates.md --- # Server Updates To ensure your Operating System stays updated with the latest security patches, Ciara configures `unattended-upgrades` for you. ## Server Reboots Some security updates requires a reboot on the server. You can disable automatic reboots or customize when these reboots should occur in your `ciara.config.json`: ::: code-group ```json [ciara.config.json] { "updates": { "reboots": { "enabled": true, "time": "03:00" } } } ``` ::: Ciara does not utilize live kernel patching solutions like [kpatch](https://github.com/dynup/kpatch) because, [as per docs](https://github.com/dynup/kpatch/blob/master/README.md): > "Kernel crashes, spontaneous reboots, and data loss may occur!" If you require high availability, please refer to our section on [High Availability](/high-availability). ## Major Updates Ciara does not configure major updates (e.g., upgrading from Debian 11 to Debian 12, or non-security dependencies updates).