airship
/
utils
Code Issues Proposed changes

Update readme

This commit is contained in:
Artem Smirnov 2018-09-13 02:15:48 +03:00
parent dcabd1ccc0
commit ebded71239
1 changed files with 88 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

216
README.md
View File

@ -4,163 +4,123 @@ Author: Artem Smirnov, Bryan Hong
Date: September 13, 2018 Date: September 13, 2018
License: Apache License, Version 2.0 License: Apache License, Version 2.0
--- ---
docker-aptly # docker-aptly
==
aptly in a container backed by nginx **docker-aptly** is container w `aptly` backed by `nginx`.
>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) **aptly** is a swiss army knife for Debian repository management: it allow you to mirror remote repositories, manage local package repositories, take snapshots, pull new versions of packages along with dependencies, publish as Debian repository. More info are on [aptly.info](http://aptly.info) and on [github](https://github.com/aptly-dev/aptly).
>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/) **nginx** is an HTTP and reverse proxy server, a mail proxy server, and a generic TCP proxy server, originally written by Igor Sysoev. More info is on [nginx.org](http://nginx.org/en/).
**NOTE:** This container and the scripts within are written to make hosting an Ubuntu mirror "as-close-to-turnkey" as possible. If you want to host a Debian mirror, you'll need to build the image yourself, see [Building the Container](#building-the-container) below ## Quickstart
Quickstart The following command will run `aptly` and `nginx` in a container:
--
The 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 ```bash
docker run \
``` --detach=true \
docker run \ --log-driver=syslog \
--detach=true \ --restart=always \
--log-driver=syslog \ --name="aptly" \
--name="aptly" \ --publish 80:80 \
--restart=always \ --volume $(pwd)/aptly_files:/opt/aptly \
--env FULL_NAME="First Last" \ --env FULL_NAME="First Last" \
--env EMAIL_ADDRESS="youremail@example.com" \ --env EMAIL_ADDRESS="youremail@example.com" \
--env GPG_PASSWORD="PickAPassword" \ --env GPG_PASSWORD="PickAPassword" \
--env HOSTNAME=aptly.example.com \ --env HOSTNAME=aptly.example.com \
--volume /dockerhost/dir/with/lots/of/space:/opt/aptly \ smirart/aptly:latest
--publish 80:80 \
bryanhong/aptly:latest
``` ```
### Runtime flags explained > 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.
``` ### Explane of the flags
--detach=true
```
run the container in the background
```
--log-driver=syslog
```
send nginx logs to syslog on the Docker host (requires Docker 1.6 or higher)
```
--name="aptly"
```
name of the container
```
--restart=always
```
automatically start the container when the Docker daemon starts
```
--env FULL_NAME="First Last"
```
the first and last name that will be associated with the GPG apt signing key
```
--env EMAIL_ADDRESS="youremail@example.com"
```
the email address that will be associated with the GPG apt signing key
```
--env GPG_PASSWORD="PickAPassword"
```
the password that will be used to encrypt the GPG apt signing key
```
--env HOSTNAME=aptly.example.com
```
the hostname of the Docker host that this container is running on
```
--volume /dockerhost/dir/with/lots/of/space:/opt/aptly
```
path that aptly will use to store its data : mapped path in the container
```
--publish 80:80
```
Docker host port : mapped port in the container
Create a mirror of Ubuntu's main repository Flag | Description
-- --- | ---
1. 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. `--detach=true` | Run the container in the background
2. Attach to the container ```docker exec -it aptly /bin/bash``` `--log-driver=syslog` | Send nginx logs to syslog on the Docker host (requires Docker 1.6 or higher)
3. 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. `--restart=always` | Automatically start the container when the Docker daemon starts
4. Run ```/opt/update_mirror.sh``` `--name="aptly"` | Name of the container
5. If the script fails due to network disconnects etc, just re-run it. `--volume $(pwd)/aptly:/opt/aptly` | Path that aptly will use to store its data : mapped path in the container
`--publish 80:80` | Docker host port : mapped port in the container
`--env FULL_NAME="First Last"` | The first and last name that will be associated with the GPG apt signing key
`--env EMAIL_ADDRESS="your@email.com"` | The email address that will be associated with the GPG apt signing key
`--env GPG_PASSWORD="PickAPassword"` | The password that will be used to encrypt the GPG apt signing key
`--env HOSTNAME=aptly.example.com` | The hostname of the Docker host that this container is running on
When the script completes, you should have a functional mirror that you can point a client to. ## Setup a client for use your repo
Point a host at the mirror
--
1. Fetch the public PGP key from your aptly repository and add it to your trusted repositories 1. Fetch the public PGP key from your aptly repository and add it to your trusted repositories
``` ```bash
wget http://FQDN.OF.APTLY/aptly_repo_signing.key wget http://YOUR_HOST_FOR_APTLY/aptly_repo_signing.key
apt-key add aptly_repo_signing.key apt-key add aptly_repo_signing.key
``` ```
2. Backup then replace /etc/apt/sources.list 2. Backup then replace /etc/apt/sources.list
``` ```bash
cp /etc/apt/sources.list /etc/apt/sources.list.bak cp /etc/apt/sources.list /etc/apt/sources.list.bak
echo "deb http://FQDN.OF.APTLY/ ubuntu main" > /etc/apt/sources.list echo "deb http://YOUR_HOST_FOR_APTLY/ ubuntu main" > /etc/apt/sources.list
apt-get update apt-get update
``` ```
You should be able to install packages at this point!
Checkout the excellent aptly documentation [here](http://www.aptly.info/doc/overview/)
Building the container > `ubuntu` & `main` may be another. It's require from your repos on aptly.
--
If you want to make modifications to the image or simply see how things work, check out this repository: ## Configure the container
``` For attach to the container and start to configure your aptly use:
git clone https://github.com/bryanhong/docker-aptly.git
```bash
docker exec -it aptly /bin/bash
``` ```
### Commands and variables Read [the official documentation](https://www.aptly.info/doc/overview/) for learn more about aptly.
* ```vars```: Variables for Docker registry, the application, and aptly repository data location For stop container use:
* ```build.sh```: Build the Docker image locally, this script will take the name of a Dockerfile as an argument, by default will build Dockerfile.
* ```run.sh```: Starts the Docker container, it the image hasn't been built locally, it is fetched from the repository set in vars
* ```push.sh```: Pushes the latest locally built image to the repository set in vars
* ```shell.sh```: get a shell within the container
### How this image/container works ```bash
docker stop aptly
```
### Create a mirror of Ubuntu's main repository
1. Attach to the container. How attach? [See this](##Configure-the-container).
2. Run `/opt/update_mirror.sh`.
By default, this script 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.
> If the script fails due to network disconnects etc, just re-run it.
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, tmux or byobu session before proceeding.
> For 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.
When the script completes, you should have a functional mirror that you can point a client to.
For create Debian's mirror use `/opt/debian_mirror.sh`.
## Building the container
If you want to customize image or build the container locally, check out this repository and build after:
```bash
git clone https://github.com/urpylka/docker-aptly.git
docker build docker-aptly
```
## How this image/container works
**Data** **Data**
All 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. All 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.
**Networking** **Networking**
By 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. By 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 to map to any port you like (see [Explane of the flags](###Explane-of-the-flags)).
**Security** **Security**
The 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. The GPG password which you specified in `GPG_PASSWORD` is stored in plain text and 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.
### Usage ## Bugs
#### Configure the container * **startup.sh**: looks like that `gpg --batch --gen-key /opt/gpg_batch` execute in separating process & next step is incorrect.
1. Configure application specific variables in ```vars```
#### Build the image
1. Run ```./build.sh```
>To build a Debian-based mirror/aptly run ```./build.sh Dockerfile.debian```
#### Start the container
1. Run ```./run.sh```
2. 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```
#### Pushing your image to the registry
If 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.
1. Authenticate to the Docker Registry ```docker login```
2. Run ```./push.sh```
3. Log into your Docker hub account and add a description, etc.
> NOTE: If your image will be used FROM other containers you might want to use ```./push.sh flatten``` to consolidate the AUFS layers into a single layer. Keep in mind, you may lose Dockerfile attributes when your image is flattened.