0
# Quarkus DevServices Deployment
1

2
Quarkus DevServices Deployment is a Maven deployment module that provides automatic configuration and orchestration of development services for Quarkus applications. It enables developers to automatically start and configure external services like databases, message brokers, and other containers during development and testing without manual setup through Docker Compose integration.
3

4
## Package Information
5

6
- **Package Name**: quarkus-devservices-deployment
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Maven Coordinates**: `io.quarkus:quarkus-devservices-deployment:3.23.0`
10
- **Installation**: Include as dependency in Quarkus extension development
11

12
## Core Imports
13

14
```java
15
import io.quarkus.devservices.deployment.DevServicesProcessor;
16
import io.quarkus.devservices.deployment.compose.ComposeDevServicesProcessor;
17
import io.quarkus.devservices.deployment.compose.ComposeProject;
18
import io.quarkus.devservices.deployment.compose.ComposeFiles;
19
```
20

21
## Basic Usage
22

23
```java
24
// Build step processor for DevServices
25
@BuildStep
26
public void configureDevServices(
27
    BuildProducer<DevServicesResultBuildItem> devServicesProducer,
28
    DockerStatusBuildItem dockerStatus) {
29
    
30
    // DevServices will automatically handle service lifecycle
31
    // No manual configuration needed for basic usage
32
}
33

34
// Creating a Compose project programmatically
35
ComposeFiles composeFiles = new ComposeFiles(List.of(composeFile));
36
ComposeProject project = new ComposeProject.Builder(composeFiles, "docker")
37
    .withProject("my-project")
38
    .withStartupTimeout(Duration.ofMinutes(2))
39
    .withStopContainers(true)
40
    .withFollowContainerLogs(true)
41
    .build();
42

43
project.start();
44
project.waitUntilServicesReady(executor);
45
```
46

47
## Error Handling
48

49
DevServices Deployment handles various error conditions and provides clear error messages:
50

51
```java
52
// Handle Docker availability issues
53
try {
54
    ComposeProject project = createComposeProject();
55
    project.start();
56
} catch (RuntimeException e) {
57
    if (e.getMessage().contains("Docker not available")) {
58
        // Handle Docker daemon not running
59
        LOG.warn("Docker is not available, skipping DevServices");
60
        return Optional.empty();
61
    }
62
    throw e;
63
}
64

65
// Handle compose file parsing errors
66
try {
67
    ComposeFile composeFile = new ComposeFile(file);
68
} catch (IllegalArgumentException e) {
69
    LOG.error("Failed to parse compose file: " + file.getName(), e);
70
    // Continue with other files or fail gracefully
71
}
72

73
// Handle service startup failures
74
try {
75
    project.waitUntilServicesReady(executor);
76
} catch (RuntimeException e) {
77
    LOG.error("Services failed to start within timeout", e);
78
    project.stop(); // Cleanup failed services
79
    throw new RuntimeException("DevServices startup failed", e);
80
}
81
```
82

83
## Architecture
84

85
Quarkus DevServices Deployment is organized around several key components:
86

87
- **Build Step Processors**: Core build-time processors that integrate with Quarkus build pipeline
88
- **Compose Management**: Docker Compose integration for service orchestration
89
- **Console Commands**: Development-time CLI commands for service management
90
- **Container Lifecycle**: Automated container startup, health checking, and cleanup
91
- **Configuration Injection**: Automatic injection of service connection details into application config
92

93
## Capabilities
94

95
### DevServices Processing
96

97
Core build step processing that orchestrates the DevServices lifecycle, provides shared networking, and configures console commands for development-time service management.
98

99
```java { .api }
100
@BuildStep
101
public DevServicesNetworkIdBuildItem networkId(
102
    Optional<DevServicesLauncherConfigResultBuildItem> devServicesLauncherConfig,
103
    Optional<DevServicesComposeProjectBuildItem> composeProjectBuildItem);
104

105
@BuildStep(onlyIf = { IsDevelopment.class })
106
public List<DevServiceDescriptionBuildItem> config(
107
    DockerStatusBuildItem dockerStatusBuildItem,
108
    BuildProducer<ConsoleCommandBuildItem> commandBuildItemBuildProducer,
109
    BuildProducer<FooterLogBuildItem> footerLogProducer,
110
    LaunchModeBuildItem launchModeBuildItem,
111
    Optional<DevServicesLauncherConfigResultBuildItem> devServicesLauncherConfig,
112
    List<DevServicesResultBuildItem> devServicesResults);
113
```
114

115
[DevServices Processing](./devservices-processing.md)
116

117
### Compose Project Management
118

119
Complete Docker Compose project lifecycle management including service discovery, startup orchestration, health checking, and configuration extraction.
120

121
```java { .api }
122
public class ComposeProject {
123
    public void start();
124
    public void waitUntilServicesReady(Executor waitOn);
125
    public void startAndWaitUntilServicesReady(Executor waitOn);
126
    public void stop();
127
    public void discoverServiceInstances(boolean checkForRequiredServices);
128
    
129
    public String getProject();
130
    public List<ComposeServiceWaitStrategyTarget> getServices();
131
    public Map<String, String> getEnvVarConfig();
132
    public Map<String, String> getExposedPortConfig();
133
    public List<Network> getNetworks();
134
    public String getDefaultNetworkId();
135
}
136

137
public static class Builder {
138
    public Builder(ComposeFiles files, String executable);
139
    public Builder withProject(String project);
140
    public Builder withStartupTimeout(Duration duration);
141
    public Builder withStopTimeout(Duration duration);
142
    public ComposeProject build();
143
}
144
```
145

146
[Compose Project Management](./compose-project.md)
147

148
### Compose File Processing
149

150
Docker Compose file parsing, validation, and service definition extraction with support for multiple compose files and project naming.
151

152
```java { .api }
153
public class ComposeFiles {
154
    public ComposeFiles(List<File> composeFiles);
155
    public Set<String> getAllServiceNames();
156
    public Map<String, ComposeServiceDefinition> getServiceDefinitions();
157
    public String getProjectName();
158
    public List<File> getFiles();
159
}
160

161
public class ComposeFile {
162
    public ComposeFile(File composeFile);
163
    public String getProjectName();
164
    public Map<String, ComposeServiceDefinition> getServiceDefinitions();
165
}
166
```
167

168
[Compose File Processing](./compose-files.md)
169

170
### Console Commands
171

172
Development-time CLI commands for listing DevServices, viewing logs, and managing container lifecycle during development.
173

174
```java { .api }
175
@GroupCommandDefinition(name = "devservices", description = "Dev Service Commands")
176
public class DevServicesCommand implements GroupCommand {
177
    public DevServicesCommand(List<DevServiceDescriptionBuildItem> serviceDescriptions);
178
    public List<Command> getCommands();
179
    public CommandResult execute(CommandInvocation commandInvocation);
180
}
181

182
@CommandDefinition(name = "list", description = "List of dev services")
183
public class DevServicesListCommand implements Command {
184
    public CommandResult execute(CommandInvocation commandInvocation);
185
}
186

187
@CommandDefinition(name = "logs", description = "Print container logs")
188
public class DevServicesLogsCommand implements Command {
189
    public CommandResult execute(CommandInvocation commandInvocation);
190
}
191
```
192

193
[Console Commands](./console-commands.md)
194

195
## Types
196

197
```java { .api }
198
// Build items used by DevServices processors
199
public class DevServicesNetworkIdBuildItem extends SimpleBuildItem {
200
    public DevServicesNetworkIdBuildItem(String networkId);
201
    public String getNetworkId();
202
}
203

204
public class DevServiceDescriptionBuildItem extends MultiBuildItem {
205
    public DevServiceDescriptionBuildItem(String name, String description, 
206
                                         RunningDevService runningDevService);
207
    public String getName();
208
    public String getDescription();
209
    public boolean hasContainerInfo();
210
    public RunningDevService.ContainerInfo getContainerInfo();
211
    public Map<String, String> getConfigs();
212
}
213

214
public class DevServicesComposeProjectBuildItem extends SimpleBuildItem {
215
    public DevServicesComposeProjectBuildItem(ComposeProject project, 
216
                                             Map<String, List<RunningContainer>> composeServices,
217
                                             String defaultNetworkId);
218
    public ComposeProject getProject();
219
    public Map<String, List<RunningContainer>> getComposeServices();
220
    public String getDefaultNetworkId();
221
}
222

223
public class DevServicesResultBuildItem extends MultiBuildItem {
224
    public DevServicesResultBuildItem(String name, String description,
225
                                     String containerId, Map<String, String> configs);
226
    public String getName();
227
    public String getDescription();
228
    public String getContainerId();
229
    public Map<String, String> getConfigs();
230
}
231

232
// Port definition for Docker containers
233
public class ExposedPort {
234
    public ExposedPort(int port);
235
    public ExposedPort(int port, InternetProtocol protocol);
236
    public int getPort();
237
    public InternetProtocol getProtocol();
238
}
239

240
// Service definition from compose file
241
public class ComposeServiceDefinition {
242
    public ComposeServiceDefinition(String serviceName, Map<String, ?> definitionMap);
243
    public String getServiceName();
244
    public String getContainerName();
245
    public List<ExposedPort> getPorts();
246
    public boolean hasHealthCheck();
247
    public Map<String, Object> getLabels();
248
    public List<String> getProfiles();
249
}
250

251
// Container wait strategy target
252
public class ComposeServiceWaitStrategyTarget implements WaitStrategyTarget, Supplier<InspectContainerResponse> {
253
    public ComposeServiceWaitStrategyTarget(DockerClient dockerClient, Container container);
254
    public String getContainerId();
255
    public String getServiceName();
256
    public int getContainerNumber();
257
    public String getContainerName();
258
    public InspectContainerResponse getContainerInfo();
259
}
260

261
// Log forwarding for containers
262
public class ContainerLogForwarder implements Closeable {
263
    public ContainerLogForwarder(DevServiceDescriptionBuildItem devService);
264
    public DevServiceDescriptionBuildItem getDevService();
265
    public boolean isRunning();
266
    public void start();
267
    public void close();
268
}
269

270
// Running container information
271
public static class RunningContainer {
272
    public RunningContainer(String containerId, String serviceName, String image,
273
                           Map<String, String> labels, Set<Integer> ports);
274
    public String getId();
275
    public String getServiceName();
276
    public String getImage();
277
    public Map<String, String> getLabels();
278
    public Set<Integer> getPorts();
279
}
280

281
// Configuration enums
282
public enum InternetProtocol {
283
    TCP, UDP
284
}
285
```