compose_validatr/
lib.rs

1//! `compose-validatr` is a library for validating and building valid [Docker Compose](https://docs.docker.com/compose/compose-file/) manifests that are not dependent on the host system.
2//!
3//! # Table of Contents
4//!
5//! - [High-level features](#high-level-features)
6//! - [Purpose](#purpose)
7//! - [Examples](#examples)
8//!
9//!
10//! # High-level Features
11//!
12//! - Create and validate a Docker Compose structure from `&str`
13//! - Access the fields for a Compose manifest
14//! - View multiple validation errors at once
15//!  
16//! # Purpose
17//!
18//! The main purpose of this library is for building and validating Docker Compose manifests
19//! in contexts that are agnostic to a host machine. This is useful for web applications
20//! that want to visualize existing Compose manifests or create valid manifests without
21//! caring if host files or devices are present.
22//!
23//! # Examples
24//!
25//! ```rust
26//! use compose_validatr::Compose;
27//!
28//! let yaml = r#"
29//! services:
30//!   gitlab:
31//!     image: gitlab/gitlab-ce:latest
32//!     container_name: gitlab
33//!     hostname: gitlab
34//!     restart: always
35//!     build:
36//!       context: .
37//!       dockerfile: webapp.Dockerfile
38//! "#;
39//!
40//! let compose = Compose::new(yaml).unwrap();
41//! compose.services.keys().for_each(|service_name| println!("Service: {service_name}"));
42//! ```
43//!
44//! ```rust
45//! use compose_validatr::Compose;
46//!
47//! let yaml = r#"
48//! version: '3.9'
49//! services:
50//!   gitlab:
51//!     image: gitlab/gitlab-ce:latest
52//!     container_name: gitlab
53//!     hostname: gitlab
54//!     restart: always
55//!     depends_on:
56//!       - postgres
57//!     ports:
58//!       - "8080:80"
59//!       - "8443:443"
60//!       - "8022:22"
61//!     environment:
62//!       GITLAB_ROOT_PASSWORD: eYPkjBbrtzX8eGVc
63//!       DATABASE_URL: "postgres://gitlab:eYPkjBbrtzX8eGVc@postgres:5432/gitlab"
64//!     volumes:
65//!       - ./gitlab/config:/etc/gitlab
66//!       - ./gitlab/logs:/var/log/gitlab
67//!       - ./gitlab/data:/var/opt/gitlab
68//!     shm_size: '256m'
69//!
70//!   registry:
71//!     image: registry:2
72//!     container_name: registry
73//!     hostname: registry
74//!     ports:
75//!       - "5000:5000"
76//!     volumes:
77//!       - registry:/var/lib/registry
78//!
79//!   sonarqube:
80//!     build:
81//!       context: ./sonarqube_image
82//!     container_name: sonarqube
83//!     hostname: sonarqube
84//!     restart: always
85//!     ports:
86//!       - "9000:9000"
87//!       - "9092:9092"
88//!     volumes:
89//!       - sonarqube:/opt/sonarqube/data
90//!       - sonarqube:/opt/sonarqube/logs
91//!       - sonarqube:/opt/sonarqube/extensions
92//!
93//!   jenkins:
94//!     build:
95//!       context: ./jenkins_image
96//!     container_name: jenkins
97//!     hostname: jenkins
98//!     restart: always
99//!     ports:
100//!       - "9080:8080"
101//!       - "50000:50000"
102//!     volumes:
103//!       - jenkins:/var/jenkins_home
104//!       - jenkins-data:/var/jenkins_home
105//!       - jenkins-docker-certs:/certs/client:ro
106//!     environment:
107//!       - JAVA_OPTS=-Djenkins.install.runSetupWizard=false
108//!       - DOCKER_HOST=tcp://docker:2376
109//!       - DOCKER_CERT_PATH=/certs/client
110//!       - DOCKER_TLS_VERIFY=1
111//!
112//!   jenkins-docker:
113//!     image: docker:dind
114//!     container_name: jenkins-docker
115//!     hostname: docker
116//!     privileged: true
117//!     environment:
118//!       - DOCKER_TLS_CERTDIR=/certs
119//!     volumes:
120//!       - /etc/docker/daemon.json:/etc/docker/daemon.json
121//!       - jenkins-docker-certs:/certs/client
122//!       - jenkins-data:/var/jenkins_home
123//!     ports:
124//!       - '2376:2376'
125//!     command: --storage-driver overlay2
126//!
127//!   postgres:
128//!     image: postgres:latest
129//!     container_name: postgres
130//!     hostname: postgres
131//!     restart: always
132//!     ports:
133//!       - "5432:5432"
134//!     volumes:
135//!       - postgres:/var/lib/postgresql/data
136//!     environment:
137//!       POSTGRES_DB: gitlab
138//!       POSTGRES_USER: gitlab
139//!       POSTGRES_PASSWORD: eYPkjBbrtzX8eGVc
140//!
141//! volumes:
142//!   sonarqube:
143//!   jenkins:
144//!   jenkins-docker-certs:
145//!   jenkins-data:
146//!   postgres:
147//!   registry:
148//!
149//! networks:
150//!   default:
151//!     driver: bridge
152//! "#;
153//!
154//! // Create a new `Compose` from the &str. This will return a Result<Compose, ValidationErrors>
155//! let compose = Compose::new(yaml);
156//! match &compose {
157//!   Ok(c) => {
158//!     // Compose is valid. A lot of Compose fields are optional, so maps are very useful here
159//!     c.version.as_ref().map(|v| println!("Version: {v}"));
160//!     ()
161//!   }
162//!   Err(errors) => {
163//!     // Compose had one or many errors
164//!     ()
165//!   }
166//! }
167//! ```
168
169#![warn(
170    clippy::all,
171    clippy::todo,
172    clippy::empty_enum,
173    clippy::inefficient_to_string,
174    clippy::str_to_string,
175    clippy::str_to_string,
176    clippy::missing_docs
177)]
178#![deny(unreachable_pub, unreachable_code, unsafe_code)]
179pub mod compose;
180pub mod configs;
181pub mod errors;
182pub mod networks;
183pub mod secrets;
184pub mod services;
185pub mod volumes;
186
187pub use crate::compose::Compose;
compose_validatr/lib.rs

compose_validatr/
lib.rs
