[github/shaarli/Shaarli.git] / doc / md / docker / docker-101.md

## Basics
Install [Docker](https://www.docker.com/), by following the instructions relevant
to your OS / distribution, and start the service.

### Search an image on [DockerHub](https://hub.docker.com/)

```bash
$ docker search debian

NAME            DESCRIPTION                                     STARS   OFFICIAL   AUTOMATED
ubuntu          Ubuntu is a Debian-based Linux operating s...   2065    [OK]
debian          Debian is a Linux distribution that's comp...   603     [OK]
google/debian                                                   47                 [OK]
```

### Show available tags for a repository
```bash
$ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
Dload  Upload   Total   Spent    Left  Speed
100  1283    0  1283    0     0    433      0 --:--:--  0:00:02 --:--:--   433
```

Sample output:
```json
[
    {
        "layer": "85a02782",
        "name": "stretch"
    },
    {
        "layer": "59abecbc",
        "name": "testing"
    },
    {
        "layer": "bf0fd686",
        "name": "unstable"
    },
    {
        "layer": "60c52dbe",
        "name": "wheezy"
    },
    {
        "layer": "c5b806fe",
        "name": "wheezy-backports"
    }
]

```

### Pull an image from DockerHub
```bash
$ docker pull repository[:tag]

$ docker pull debian:wheezy
wheezy: Pulling from debian
4c8cbfd2973e: Pull complete
60c52dbe9d91: Pull complete
Digest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe
Status: Downloaded newer image for debian:wheezy
```

Docker re-uses layers already downloaded. Iow. if you have only images based on some Alpine or Ubuntu version for example, those can share disk space.

### Start a container
A container is an instance created from an image, that can be run and that keeps running until its main process exits. Or until the user stops the container. 

The simplest way to start a container from image is ``docker run``. It also pulls the image for you if it is not locally available. For more advanced use, refer to ``docker create``.

Note that stopped containers are not destroyed, unless you specify ``--rm``.
To view all created, running and stopped containers, enter:

```bash
$ docker ps -a
```

Some containers may be designed or configured to be restarted, others are not. Note that both network ports and volumes of a container are created on start, and not editable later.

### Access a running container
A running container is accessible using ``docker exec``, or ``docker copy``.
You can use ``exec`` to start a root shell in the Shaarli container:
```bash
$ docker exec -ti <container-name-or-id> bash
```
Note the names and ID's of containers are list in ``docker ps``. You an even type only one or two letters of the ID, given they are unique.

Access can also be through one or more network ports, or disk volumes. Both are specified on and fixed on ``docker create`` or ``run``.

### Docker disk use
Trying out different images can fill some gigabytes of disk quickly. Besides images, the docker volumes usually take up most disk space.

If you care only about trying out docker and not about what is running or saved,
the following commands should help you out quickly:

```bash
$ docker rmi -f $(docker images -aq) # remove or mark all images for disposal
$ docker volume rm $(docker volume ls -q) # remove all volumes
```
Commit	Line	Data
53ed6d7d	1	## Basics
	2	Install [Docker](https://www.docker.com/), by following the instructions relevant
	3	to your OS / distribution, and start the service.
	4
	5	### Search an image on [DockerHub](https://hub.docker.com/)
	6
	7	```bash
	8	$ docker search debian
	9
	10	NAME DESCRIPTION STARS OFFICIAL AUTOMATED
	11	ubuntu Ubuntu is a Debian-based Linux operating s... 2065 [OK]
	12	debian Debian is a Linux distribution that's comp... 603 [OK]
	13	google/debian 47 [OK]
	14	```
	15
	16	### Show available tags for a repository
	17	```bash
	18	$ curl https://index.docker.io/v1/repositories/debian/tags \| python -m json.tool
	19
	20	% Total % Received % Xferd Average Speed Time Time Time Current
	21	Dload Upload Total Spent Left Speed
	22	100 1283 0 1283 0 0 433 0 --:--:-- 0:00:02 --:--:-- 433
	23	```
	24
	25	Sample output:
	26	```json
	27	[
	28	{
	29	"layer": "85a02782",
	30	"name": "stretch"
	31	},
	32	{
	33	"layer": "59abecbc",
	34	"name": "testing"
	35	},
	36	{
	37	"layer": "bf0fd686",
	38	"name": "unstable"
	39	},
	40	{
	41	"layer": "60c52dbe",
	42	"name": "wheezy"
	43	},
	44	{
	45	"layer": "c5b806fe",
	46	"name": "wheezy-backports"
	47	}
	48	]
	49
	50	```
	51
	52	### Pull an image from DockerHub
	53	```bash
	54	$ docker pull repository[:tag]
	55
	56	$ docker pull debian:wheezy
	57	wheezy: Pulling from debian
	58	4c8cbfd2973e: Pull complete
	59	60c52dbe9d91: Pull complete
	60	Digest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe
	61	Status: Downloaded newer image for debian:wheezy
	62	```
22a30602 B	63
	64	Docker re-uses layers already downloaded. Iow. if you have only images based on some Alpine or Ubuntu version for example, those can share disk space.
	65
	66	### Start a container
	67	A container is an instance created from an image, that can be run and that keeps running until its main process exits. Or until the user stops the container.
	68
	69	The simplest way to start a container from image is ``docker run``. It also pulls the image for you if it is not locally available. For more advanced use, refer to ``docker create``.
	70
	71	Note that stopped containers are not destroyed, unless you specify ``--rm``.
	72	To view all created, running and stopped containers, enter:
	73
	74	```bash
	75	$ docker ps -a
	76	```
	77
	78	Some containers may be designed or configured to be restarted, others are not. Note that both network ports and volumes of a container are created on start, and not editable later.
	79
	80	### Access a running container
	81	A running container is accessible using ``docker exec``, or ``docker copy``.
	82	You can use ``exec`` to start a root shell in the Shaarli container:
	83	```bash
	84	$ docker exec -ti <container-name-or-id> bash
	85	```
	86	Note the names and ID's of containers are list in ``docker ps``. You an even type only one or two letters of the ID, given they are unique.
	87
	88	Access can also be through one or more network ports, or disk volumes. Both are specified on and fixed on ``docker create`` or ``run``.
	89
	90	### Docker disk use
	91	Trying out different images can fill some gigabytes of disk quickly. Besides images, the docker volumes usually take up most disk space.
	92
	93	If you care only about trying out docker and not about what is running or saved,
	94	the following commands should help you out quickly:
	95
	96	```bash
	97	$ docker rmi -f $(docker images -aq) # remove or mark all images for disposal
	98	$ docker volume rm $(docker volume ls -q) # remove all volumes
	99	```