Skip to content

Commit b32e9d7

Browse files
volmasoftvolmasoft
authored
adds Dockerfile for proxy and documents its use (#20)
1 parent 5983012 commit b32e9d7

File tree

3 files changed

+216
-0
lines changed

3 files changed

+216
-0
lines changed

‎DOCKER.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
<!--
2+
Licensed to the Apache Software Foundation (ASF) under one or more
3+
contributor license agreements. See the NOTICE file distributed with
4+
this work for additional information regarding copyright ownership.
5+
The ASF licenses this file to You under the Apache License, Version 2.0
6+
(the "License"); you may not use this file except in compliance with
7+
the License. You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
-->
17+
18+
# accumulo-proxy-docker
19+
This documentation covers how to stand up [accumulo-proxy](https://github.com/apache/accumulo-proxy/) within a Docker container.
20+
21+
The guide covers:
22+
* Building the image
23+
* Configuring the `proxy.properties` file
24+
* Selecting an appropriate networking choice
25+
* Starting and stopping the container
26+
* Basic troubleshooting tips
27+
28+
It is not recommended using this guide for a production instance of accumulo-proxy at this time.
29+
30+
## Build the image
31+
Firstly you will need the tarball of accumulo-proxy, this is documented in the [README.md](README.md) but for simplicity run:
32+
```commandline
33+
mvn clean package -Ptarball
34+
```
35+
36+
Once you have the tarball (should be in ./target/ folder) then invoke the Docker build command to create a container image.
37+
```commandline
38+
docker build -t accumulo-proxy:latest .
39+
```
40+
41+
## Default Configuration and Quickstart
42+
By default, the container image expects the following to be true:
43+
1. Your Accumulo instance name is "myinstance"
44+
2. Your ZooKeeper is available (and reachable from the container) at localhost:2181
45+
46+
You can start the proxy using:
47+
```commandline
48+
docker run --rm -d -p 42424:42424 --network="host" --name accumulo-proxy accumulo-proxy:latest;
49+
```
50+
51+
## Custom proxy.properties
52+
If you wish to create advanced proxy.properties configuration changes, you should look to volume mount these in when you invoke the `docker run` command, an example is:
53+
```commandline
54+
docker run --rm -d -p 42424:42424 -v /path/to/proxy.properties:/opt/accumulo-proxy/conf/proxy.properties --network="host" --name accumulo-proxy accumulo-proxy:latest
55+
```
56+
57+
## Networking configuration
58+
Container networking can be a very specialised subject therefore we document two common practices that should cover the majority of use cases for development.
59+
60+
The proxy container must be able to access both Accumulo and ZooKeeper.
61+
62+
The ZooKeeper location can be configured in the `conf/proxy.properties` file, so you can override this to an acceptable value (see "Custom proxy.properties" section)
63+
64+
In order to communicate with Accumulo the container will need to be able to resolve the FQDN that the servers have registered in ZooKeeper. If using [fluo-uno](https://github.com/apache/fluo-uno) this is very likely the hostname of your development environment. We'll call this my.host.com and IP 192.168.0.1 for the rest of this document.
65+
66+
### Host networking
67+
68+
Host networking is the simplest mechanism but generally only works for linux hosts where Docker has been installed on 'bare metal' e.g. through an RPM.
69+
70+
You can test if this will work for you by executing the following steps
71+
72+
Start the accumulo-proxy container and enter it
73+
```commandline
74+
docker run -it --rm -p 42424:42424 --network="host" --name accumulo-proxy accumulo-proxy:latest bash;
75+
```
76+
77+
Once inside the container, execute the curl command to attempt to connect to the monitor webserver:
78+
```commandline
79+
curl my.host.com:9995
80+
```
81+
82+
If the terminal returns an error such as:
83+
```
84+
curl: (7) Failed to connect to my.host.com 9995: Connection refused
85+
```
86+
then your container cannot see the host, and you will need to look at the next section (Non-Host networking).
87+
88+
If you receive the HTML for the monitor web page then host networking will work for you and you can add `--network="host"` to each Docker command going forward.
89+
90+
An example of using host networking:
91+
```commandline
92+
docker run --rm -d -p 42424:42424 --network="host" --name accumulo-proxy accumulo-proxy:latest
93+
```
94+
95+
Note: You do not need to map your ports (-p) if using host networking, but we include it for clarity.
96+
97+
For more details see the official Docker documentation: [Use host Networking](https://docs.docker.com/network/host)
98+
99+
### Non-Host networking
100+
If you run outside of a single node linux installation, e.g. Docker for Mac, Docker for Windows or use a VM to isolate your Docker engine then you will likely need to take this path.
101+
102+
Docker allows you to supply additional addresses to be resolved by the container, and these are automatically added by Docker to the /etc/hosts
103+
104+
For each host add a `--add-host FQDN:IP` entry to your Docker run command, you can add multiple entries if need to, see the official docs covering [network settings](https://docs.docker.com/engine/reference/run/#network-settings).
105+
106+
An example of using this approach:
107+
108+
```commandline
109+
docker run --rm -d -p 42424:42424 --add-host "my.host.com:192.168.0.1" --name accumulo-proxy accumulo-proxy:latest
110+
```
111+
112+
## Cleanup
113+
Once completed you should stop and remove the container.
114+
```commandline
115+
docker stop accumulo-proxy;
116+
docker rm accumulo-proxy;
117+
```
118+
119+
## Troubleshooting
120+
It can often be difficult to know where to start with troubleshooting inside containers, if you need to enter the container without starting the proxy we support this:
121+
```commandline
122+
docker run -it --rm -p 42424:42424 --network="host" --name accumulo-proxy accumulo-proxy:latest bash
123+
```
124+
125+
The container is very slim so if need be you can add additional tools using `apt`.
126+
127+
If you wish to manually execute the accumulo-proxy in the container you can:
128+
```commandline
129+
/opt/accumulo-proxy/bin/accumulo-proxy -p /opt/accumulo-proxy/conf/proxy.properties
130+
```
131+
132+
Some resources for additional help:
133+
* [Main Accumulo Website](https://accumulo.apache.org/)
134+
* [Contact Us page](https://accumulo.apache.org/contact-us/)

‎Dockerfile‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one or more
2+
# contributor license agreements. See the NOTICE file distributed with
3+
# this work for additional information regarding copyright ownership.
4+
# The ASF licenses this file to You under the Apache License, Version 2.0
5+
# (the "License"); you may not use this file except in compliance with
6+
# the License. You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
16+
FROM openjdk:8
17+
18+
EXPOSE 42424
19+
20+
WORKDIR /opt/accumulo-proxy
21+
22+
ARG HADOOP_VERSION=3.2.1
23+
ARG ZOOKEEPER_VERSION=3.5.7
24+
ARG ACCUMULO_VERSION=2.0.0
25+
ARG ACCUMULO_PROXY_VERSION=2.0.0-SNAPSHOT
26+
27+
ARG HADOOP_HASH=a57962a24d178193349917730bf95cdc99bde9df
28+
ARG ZOOKEEPER_HASH=619928c8553b62775119e3d7d143a4714a160365
29+
ARG ACCUMULO_HASH=b72bf5c3dcaa25387933a032925046234f30e17a
30+
31+
# Download from Apache mirrors instead of archive #9
32+
ENV APACHE_DIST_URLS \
33+
https://www.apache.org/dyn/closer.cgi?action=download&filename= \
34+
# if the version is outdated (or we're grabbing the .asc file), we might have to pull from the dist/archive :/
35+
https://www-us.apache.org/dist/ \
36+
https://www.apache.org/dist/ \
37+
https://archive.apache.org/dist/
38+
39+
RUN set -eux; \
40+
download_bin() { \
41+
local f="$1"; shift; \
42+
local hash="$1"; shift; \
43+
local distFile="$1"; shift; \
44+
local success=; \
45+
local distUrl=; \
46+
for distUrl in ${APACHE_DIST_URLS}; do \
47+
if wget -nv -O "/tmp/${f}" "${distUrl}${distFile}"; then \
48+
success=1; \
49+
# Checksum the download
50+
echo "${hash}" "/tmp/${f}" | sha1sum -c -; \
51+
break; \
52+
fi; \
53+
done; \
54+
[ -n "${success}" ]; \
55+
};\
56+
\
57+
download_bin "apache-zookeeper.tar.gz" "${ZOOKEEPER_HASH}" "zookeeper/zookeeper-${ZOOKEEPER_VERSION}/apache-zookeeper-${ZOOKEEPER_VERSION}-bin.tar.gz"; \
58+
download_bin "hadoop.tar.gz" "$HADOOP_HASH" "hadoop/core/hadoop-${HADOOP_VERSION}/hadoop-$HADOOP_VERSION.tar.gz"; \
59+
download_bin "accumulo.tar.gz" "${ACCUMULO_HASH}" "accumulo/${ACCUMULO_VERSION}/accumulo-${ACCUMULO_VERSION}-bin.tar.gz";
60+
61+
# Install the dependencies into /opt/
62+
RUN tar xzf /tmp/hadoop.tar.gz -C /opt/ && ln -s /opt/hadoop-${HADOOP_VERSION} /opt/hadoop
63+
RUN tar xzf /tmp/apache-zookeeper.tar.gz -C /opt/ && ln -s /opt/apache-zookeeper-${ZOOKEEPER_VERSION}-bin /opt/apache-zookeeper
64+
RUN tar xzf /tmp/accumulo.tar.gz -C /opt/ && ln -s /opt/accumulo-${ACCUMULO_VERSION} /opt/accumulo && sed -i 's/\${ZOOKEEPER_HOME}\/\*/\${ZOOKEEPER_HOME}\/\*\:\${ZOOKEEPER_HOME}\/lib\/\*/g' /opt/accumulo/conf/accumulo-env.sh
65+
66+
ENV HADOOP_HOME /opt/hadoop
67+
ENV ZOOKEEPER_HOME /opt/apache-zookeeper
68+
ENV ACCUMULO_HOME /opt/accumulo
69+
70+
# Add the proxy binary
71+
COPY target/accumulo-proxy-${ACCUMULO_PROXY_VERSION}-bin.tar.gz /tmp/
72+
RUN tar xzf /tmp/accumulo-proxy-${ACCUMULO_PROXY_VERSION}-bin.tar.gz -C /opt/accumulo-proxy --strip 1
73+
ENV ACCUMULO_PROXY_HOME /opt/accumulo-proxy
74+
75+
# Ensure Accumulo is on the path.
76+
ENV PATH "${PATH}:${ACCUMULO_HOME}/bin"
77+
78+
CMD ["/opt/accumulo-proxy/bin/accumulo-proxy", "-p", "/opt/accumulo-proxy/conf/proxy.properties"]

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,10 @@ Thrift language binding).
4141
./bin/accumulo-proxy -p conf/proxy.properties
4242
```
4343
44+
# Docker Environment
45+
46+
The Accumulo Proxy can also now be packaged and started in a Docker container, see the [DOCKER.md](DOCKER.md) for full details.
47+
4448
# Build language specific bindings
4549
4650
Bindings have been built in `src/main/` for Java, Python, and Ruby.

0 commit comments

Comments
 (0)