# Deployment options

You can run the yc agent in the following 3 different ways:

Run target application and yc agent inside separate container (sidecar)
Run target application and yc agent inside same container
Run target application in container and yc agent on the Host

Let’s discuss each option in more details:

# 1. Run target application and yc agent inside separate container (sidecar)

You can run your target java applications inside a container and install the yc agent inside a separate container (sidecar container) on the same host. The yc agent can capture troubleshooting artifacts from the java application running inside other containers on the same host.

In this case, you may need to pass the --pid=host argument when you start the yc agent container so that the yc agent container can see the target processes running inside other containers on the same host.

How to run yc agent inside Docker container (Without Kubernetes)?

Create config.yaml file to configure yc agent. Please visit All Agent Argument page to see how to configure the yc agent.
We have an offical docker image of yc agent "ycrash/yc-agent:latest". You can directly use this image to run the yc agent in container.

But if you want to build your own docker image of yc agent then please visit the Run your own docker image in this page.

Here is an example of running yc agent in a container using official docker image:

docker run --init -d -ti --rm -p 8085:8085 --name yc-agent --pid=host -v $(pwd)/config.yaml:/opt/workspace/yc-agent/config.yaml ycrash/yc-agent:latest

Now the yc agent is ready to capture artifacts from the target application. By default, the yc agent listens to port 8085. If you want to change it to some other port then you can configure it in config.yaml file

# 2. Run target application and yc agent inside same container

Let’s use buggyapp (opens new window) as a target application in this example. We will run buggyapp and yc agent inside the same container. You can replace buggyapp with your java application.

In the below example we used s6-overlay to supervise multiple processes. It is needed to run more than one process in the container because the container's entrypoint supports only one process. In order to support multi processes (your application + yc agent), s6-overlay will be the parent and it will run your application and yc agent as it's children.

You can run yc agent with your preferred multi process supervisor. Let's follow the below steps to run buggyapp and yc agent:

Create a Dockerfile to run buggyapp and yc agent inside the same Docker container. Here is a sample Dockerfile:

# Install packages required by ycrash to capture system diagnosis
RUN apt-get update \
  && apt-get upgrade -y \
  && apt-get install -y unzip procps net-tools \
  && rm -rf /var/lib/apt/lists/*

# Setup yc agent
RUN mkdir -p /opt/workspace/yc-agent
RUN cd /opt/workspace/yc-agent \
  && curl -fsSL https://tier1app.com/dist/ycrash/yc-agent-latest.zip -o yc-agent-latest.zip \
  && unzip yc-agent-latest.zip \
  && rm yc-agent-latest.zip \
  && chmod +x /opt/workspace/yc-agent/yc

# Setup s6-overlay for container init to supervise multi processes.
ADD https://github.com/just-containers/s6-overlay/releases/download/v2.2.0.1/s6-overlay-amd64-installer /tmp/
RUN chmod +x /tmp/s6-overlay-amd64-installer && /tmp/s6-overlay-amd64-installer /

# Add your app and yc-agent to ./services.d
COPY ./services.d /etc/services.d

# Setup your application here. In this example, we are using buggyApp
RUN mkdir -p /opt/workspace/buggyapp
WORKDIR /opt/workspace/buggyapp

RUN curl -fsSL https://tier1app.com/dist/buggyapp/buggyapp-latest.zip -o buggyapp-latest.zip \
&& unzip buggyapp-latest.zip \
&& rm buggyapp-latest.zip

# buggyapp
EXPOSE 9010

# yc-agent
EXPOSE 8085
ENTRYPOINT ["/init"]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

Create config.yaml file to configure yc agent. Please visit All Agent Argument page, to see how to configure the yc agent.
Next, create a services.d directory and add the following files inside it:

a) ./services.d/{yourapp}/run file -

Create a new file with the name "run" inside ./services.d/buggyapp directory. Add the below content inside the run file.

#!/usr/bin/with-contenv bash
cd /opt/workspace/buggyapp

java -Xmx2g -DlogDir=. -DuploadDir=. -jar webapp-runner-8.0.33.4.jar --port 9010 buggyapp.war

1
2
3
4

b) ./services.d/{yourapp}/finish file -

Create a new file with the name "finish" inside ./services.d/buggyapp directory. Add the below content inside the finish file.

#!/usr/bin/execlineb -S0
s6-svscanctl -t /var/run/s6/services

1
2

c) ./services.d/yc-agent/run file -

Create a new file with the name "run" inside ./services.d/yc-agent directory. Add the below content inside the run file.

#!/usr/bin/with-contenv bash
cd /opt/workspace/yc-agent
./yc -c config.yaml -a buggyapp -m3

1
2
3

In the above code snippet, we are launching yCrash agent in M3 mode. You may want to configure the M3 related arguments in your config.yaml file. Please visit here to learn about M3. The yCrash agent can be launched in 3 different modes. If you wish to launch yCrash agent in any other mode then you can change the command in ./services.d/yc-agent file accordingly.

d) ./services.d/yc-agent/finish file -

Create a new file with the name "finish" inside ./services.d/yc-agent directory. Add the below content inside the finish file.

#!/usr/bin/execlineb -S0
s6-svscanctl -t /var/run/s6/services

1
2

Build the docker image.

docker build -t buggyapp .

Run the docker container

docker run -ti -d --rm -p 9010:9010 -p 8085:8085 \
--name buggyapp \
-v $(pwd)/config.yaml:/opt/workspace/yc-agent/config.yaml \   
buggyapp

1
2
3
4

# 3. Run target application in container and yc agent on the Host

You can run your target java application inside a container and install the yCrash agent on the host. The yc agent will capture troubleshooting artifacts from the java process running inside the containers on the same host.

You can download the latest yc agent from here (opens new window).

If you want to learn how to trigger a yc agent, please visit the Quick Start Guide page.

TIP

If you get an error while running yCrash agent in Alpine docker container, please install a libec6-compat package in your Alpine docker container. For example,

RUN apk add --no-cache libc6-compat

# Run your own docker image

If you wish to build your own Docker image of yc agent then follow the below instructions:

Create a new Docker file. Here is a sample Dockerfile:

FROM adoptopenjdk/openjdk11:debian

# Install packages required by ycrash to capture system diagnosis
RUN apt-get update \
  && apt-get upgrade -y \
  && apt-get install -y unzip procps net-tools \
  && rm -rf /var/lib/apt/lists/*

# Setup yc-agent
RUN mkdir -p /opt/workspace/yc-agent
RUN cd /opt/workspace/yc-agent \
  && curl -fsSL https://tier1app.com/dist/ycrash/yc-agent-latest.zip -o yc-agent-latest.zip \
  && unzip yc-agent-latest.zip \
  && rm yc-agent-latest.zip \
  && chmod +x /opt/workspace/yc-agent/yc

WORKDIR /opt/workspace/yc-agent

# yc-agent
EXPOSE 8085

ENTRYPOINT ["./yc", "-c", "config.yaml"]
#ENTRYPOINT ["/bin/bash"]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Create config.yaml file to configure yc agent. Please visit All Agent Argument page to see how to configure the yc agent.
Build the docker image

docker build -t yc-agent .

Run the docker container

docker run --init -d -ti --rm -p 8085:8085 --name yc-agent --pid=host -v $(pwd)/config.yaml:/opt/workspace/yc-agent/config.yaml yc-agent