summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBryan <bryan@turbojets.net>2016-02-10 22:17:38 -0800
committerBryan <bryan@turbojets.net>2016-02-10 22:17:38 -0800
commit475bd0ea5b114fe516001a0d8d18ab88686bde6c (patch)
treee14a45916448d74ba066f0a000f6d65d86106c1f
parent8160dec7936b8ebca386f333e5673ffc4de0709c (diff)
README appropriate for github and dockerhub
Managing a single README is easier than maintaining two
-rw-r--r--README.md169
1 files changed, 120 insertions, 49 deletions
diff --git a/README.md b/README.md
index c366956..9127434 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,117 @@
1#docker-aptly 1docker-aptly
2==
3
4aptly in a container backed by nginx
5
6>aptly is a swiss army knife for Debian repository management: it allows you to mirror remote repositories, manage local package repositories, take snapshots, pull new versions of packages along with dependencies, publish as Debian repository. [aptly.info](http://aptly.info)
7
8>nginx [engine x] is an HTTP and reverse proxy server, a mail proxy server, and a generic TCP proxy server, originally written by Igor Sysoev [nginx.org](http://nginx.org/en/)
9
10Quickstart
11--
12
13The following command will run aptly and nginx in a container, if you want to customize or build the container locally, skip to [Building the Container](#building-the-container) below
14
15```
16docker run \
17 --detach=true \
18 --log-driver=syslog \
19 --name="aptly" \
20 --restart=always \
21 --env FULL_NAME="First Last" \
22 --env EMAIL_ADDRESS="youremail@example.com" \
23 --env GPG_PASSWORD="PickAPassword" \
24 --env HOSTNAME=aptly.example.com \
25 --volume /dockerhost/dir/with/lots/of/space:/opt/aptly \
26 --publish 80:80 \
27 bryanhong/aptly:latest
28```
29
30### Runtime flags explained
31
32```
33--detach=true
34```
35run the container in the background
36```
37--log-driver=syslog
38```
39send nginx logs to syslog on the Docker host (requires Docker 1.6 or higher)
40```
41--name="aptly"
42```
43name of the container
44```
45--restart=always
46```
47automatically start the container when the Docker daemon starts
48```
49--env FULL_NAME="First Last"
50```
51the first and last name that will be associated with the GPG apt signing key
52```
53--env EMAIL_ADDRESS="youremail@example.com"
54```
55the email address that will be associated with the GPG apt signing key
56```
57--env GPG_PASSWORD="PickAPassword"
58```
59the password that will be used to encrypt the GPG apt signing key
60```
61--env HOSTNAME=aptly.example.com
62```
63the hostname of the Docker host that this container is running on
64```
65--volume /dockerhost/dir/with/lots/of/space:/opt/aptly
66```
67path that aptly will use to store its data : mapped path in the container
68```
69--publish 80:80
70```
71Docker host port : mapped port in the container
72
73Create a mirror of Ubuntu's main repository
74--
751. The initial download of the repository may take quite some time depending on your bandwidth limits, it may be in your best interest to open a screen or tmux session before proceeding.
762. Attach to the container ```docker exec -it aptly /bin/bash```
773. By default, ```/opt/update_mirror.sh``` will automate the creation of an Ubuntu 14.04 Trusty repository with the main and universe components, you can adjust the variables in the script to suit your needs.
784. Run ```/opt/update_mirror.sh```
795. If the script fails due to network disconnects etc, just re-run it.
80
81When the script completes, you should have a functional mirror that you can point a client to.
82
83Point a host at the mirror
84--
2 85
3Dockerfile and support scripts to run aptly in a container backed by nginx. 861. Fetch the public PGP key from your aptly repository and add it to your trusted repositories
87
88 ```
89 wget http://FQDN.OF.APTLY/aptly_repo_key.pub
90 apt-key add aptly_repo_key.pub
91 ```
92
932. Backup then replace /etc/apt/sources.list
4 94
5from [aptly.info](http://aptly.info): 95 ```
6>aptly is a swiss army knife for Debian repository management: it allows you to mirror remote repositories, manage local package repositories, take snapshots, pull new versions of packages along with dependencies, publish as Debian repository. 96 cp /etc/apt/sources.list /etc/apt/sources.list.bak
97 echo "deb http://FQDN.OF.APTLY/ ubuntu main" > /etc/apt/sources.list
98 apt-get update
99 ```
100
101 You should be able to install packages at this point!
102
103Checkout the excellent aptly documentation [here](http://www.aptly.info/doc/overview/)
7 104
8If you don't plan on customizing the Dockerfile in this repository, simply follow the instructions [here](https://hub.docker.com/r/bryanhong/aptly/) instead. 105Building the container
106--
9 107
10##Requirements / Dependencies 108If you want to make modifications to the image or simply see how things work, check out this repository:
11 109
12* Docker 1.6 or higher, we are using the Docker syslog driver in this container and this feature made its debut in 1.6 110```
13* ```vars``` needs to be populated with the appropriate variables. 111git clone https://github.com/bryanhong/docker-aptly.git
112```
14 113
15##Commands and variables 114### Commands and variables
16 115
17* ```vars```: Variables for Docker registry, the application, and aptly repository data location 116* ```vars```: Variables for Docker registry, the application, and aptly repository data location
18* ```build.sh```: Build the Docker image locally 117* ```build.sh```: Build the Docker image locally
@@ -20,61 +119,33 @@ If you don't plan on customizing the Dockerfile in this repository, simply follo
20* ```push.sh```: Pushes the latest locally built image to the repository set in vars 119* ```push.sh```: Pushes the latest locally built image to the repository set in vars
21* ```shell.sh```: get a shell within the container 120* ```shell.sh```: get a shell within the container
22 121
23##How this image/container works 122### How this image/container works
123
124**Data**
125All of aptly's data (including PGP keys and GPG keyrings) is bind mounted outside of the container to preserve it if the container is removed or rebuilt. Set the location for the bind mount in ```vars``` before starting the container. If you're going to host a mirror of Ubuntu's main repository, you'll need upwards of 80GB+ (x86_64 only) of free space as of Feb 2016, plan for growth.
24 126
25####Data 127**Networking**
26All of aptly's data (including PGP keys and GPG keyrings) is bind mounted outside of the container to preserve it if the container is removed or rebuilt. Set the location for the bind mount in ```vars``` before starting the container. If you're going to host a mirror of Ubuntu's main repository, you'll need upwards of 35GB of free space as of Feb 2016, plan for growth.
27####Networking
28By default, Docker will map port 80 on the Docker host to port 80 within the container where nginx is configured to listen. You can change the external listening port in ```vars``` to map to any port you like. 128By default, Docker will map port 80 on the Docker host to port 80 within the container where nginx is configured to listen. You can change the external listening port in ```vars``` to map to any port you like.
29####Security 129
130**Security**
30The GPG password you set in ```vars``` is stored in plain text and is visible as an environment variable inside the container. It is set as an enviornment variable to allow for automation of repository updates without user interaction. The GPG password can be removed completely but it is safer to encrypt the GPG keyrings because they are bind mounted outside the container to avoid the necessity of regenerating/redistributing keys if the container is removed or rebuilt. 131The GPG password you set in ```vars``` is stored in plain text and is visible as an environment variable inside the container. It is set as an enviornment variable to allow for automation of repository updates without user interaction. The GPG password can be removed completely but it is safer to encrypt the GPG keyrings because they are bind mounted outside the container to avoid the necessity of regenerating/redistributing keys if the container is removed or rebuilt.
31 132
32##Usage 133### Usage
33 134
34####Configure the container 135#### Configure the container
35 136
361. Configure application specific variables in ```vars``` 1371. Configure application specific variables in ```vars```
37 138
38####Build the image 139#### Build the image
39 140
401. Run ```./build.sh``` 1411. Run ```./build.sh```
41 142
42####Start the container 143#### Start the container
43 144
441. Run ```./run.sh``` 1451. Run ```./run.sh```
452. Wait until the GPG keyrings are created (not 0 bytes) before proceeding (it can take a few minutes). They will be in the bind mount location you chose in ```vars``` 1462. Wait until the GPG keyrings are created (not 0 bytes) before proceeding (it can take a few minutes). They will be in the bind mount location you chose in ```vars```
46
47####Create a mirror of Ubuntu's main repository
481. The initial download of the repository may take quite some time depending on your bandwidth limits, it may be in your best interest to open a tmux or screen session before proceeding.
492. Attach to the container ```./shell.sh```
503. By default, ```/opt/update_mirror.sh``` will automate the creation of an Ubuntu 14.04 Trusty repository, if you want a different release, modify the variables in the script.
514. Run ```/opt/update_mirror.sh```
525. If the script fails due to network disconnects etc, just re-run it.
53
54When the script completes, you should have a functional mirror that you can point a client to.
55
56####Point a host at the mirror
57
581. Fetch the public PGP key from your aptly repository and add it to your trusted repositories
59
60 ```
61 wget http://FQDN.OF.APTLY/aptly_repo_signing.key
62 apt-key add aptly_repo_signing.key
63 ```
64
652. Backup then replace /etc/apt/sources.list
66
67 ```
68 cp /etc/apt/sources.list /etc/apt/sources.list.bak
69 echo "deb http://FQDN.OF.APTLY/ RELEASE_NAME main" > /etc/apt/sources.list
70 apt-get update
71 ```
72
73 You should be able to install packages at this point!
74
75Checkout the excellent aptly documentation [here](http://www.aptly.info/doc/overview/)
76 147
77####Pushing your image to the registry 148#### Pushing your image to the registry
78 149
79If you're happy with your container and ready to share with others, push your image up to a [Docker registry](https://docs.docker.com/docker-hub/) and save any other changes you've made so the image can be easily changed or rebuilt in the future. 150If you're happy with your container and ready to share with others, push your image up to a [Docker registry](https://docs.docker.com/docker-hub/) and save any other changes you've made so the image can be easily changed or rebuilt in the future.
80 151