Docs improvements #2687

gsaslis · 2017-12-01T19:24:55Z

Various all-round improvements to docker-related documentation, especially focused at improving the onboarding experience for new devs coming to try out RestComm.

These are mainly driven by the introduction of a Docker compose file that will take over the role of explaining the suitable options, while at the same time acting as an executable descriptor.

i.e. instead of writing docs to explain the docker run params, we can now both use the params and document them, both in one place (the docker compose descriptor).

The only command a new developer will have to run to start trying out RestComm is docker-compose up

The descriptor comes with “sane defaults” for a development / standalone environment and is NOT intended for use in a production environment.

Were not included in #2382

reference file had been moved to `env_files` subdir in RestComm/RestComm-Docker repo, from the `scripts` dir. fixes #2675

Goal is to reduce number of docs (that can become outdated) and focus on getting smooth onboarding Since we're moving more and more in the docker direction and our docker images are becoming our binaries (taking that role over from our JARs), this will be less and less relevant anyway.

These topics are all covered in the `docker-compose.yml` file that is coming up.

Environment variables are now documented in (the upcoming, hold your horses... ) `docker-compose.yml`

Again, documentation has been replaced / moved to the file descriptor. Also some info in the ports guide (USE_STANDARD_SIP_PORTS, USE_STANDARD_HTTP_PORTS) is now outdated

If you've been reading the previous commits, you *know* you've been waiting for this!!

gsaslis · 2017-12-01T19:26:37Z

this also fixes #2675

gsaslis · 2017-12-04T18:27:34Z

@deruelle do you think this (and in particular b00ee28 ) solves #1459?

deruelle · 2017-12-05T08:21:53Z

@gsaslis on my linux box here I tried the docker compose up but got some issues on versions, see below. any clues ?

jean@jean-XPS-15-9560:~/workspaces/Restcomm-Connect$ docker-compose upERROR: Version in "./docker-compose.yml" is unsupported. You might be seeing this error because you're using the wrong Compose file version. Either specify a version of "2" (or "2.0") and place your service definitions under the `services` key, or omit the `version` key and place your service definitions at the root of the file to use version 1.
For more on the Compose file format versions, see https://docs.docker.com/compose/compose-file/
jean@jean-XPS-15-9560:~/workspaces/Restcomm-Connect$ docker --version
Docker version 17.11.0-ce, build 1caf76c
jean@jean-XPS-15-9560:~/workspaces/Restcomm-Connect$

I removed the version from the docker-compose.yml and was faced with the following:

jean@jean-XPS-15-9560:~/workspaces/Restcomm-Connect$ docker-compose up
ERROR: The Compose file './docker-compose.yml' is invalid because:
Unsupported config option for volumes: 'hsql_data'
Unsupported config option for services: 'restcomm'

deruelle · 2017-12-05T08:23:12Z

...ces-asciidoc/src/main/asciidoc/configuration/docker/Restcomm - Docker Quick Start Guide.adoc

-Text-to-Speech with VoiceRSS
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* Tag "latest". Points to the latest binary from the Continuous Delivery server. Uses the https://github.com/RestComm/Restcomm-Connect[master] development branch : restcomm/restcomm:latest. *We don't advice to use "latest" tag for production as it is constantly changing, and as well new features and fixes may not be documented.
+* Tag "7.7.0" pointing to current specific GA release (v770ga).


The latest release is 8.2.1.GA in the community https://github.com/RestComm/Restcomm-Connect/releases/tag/8.2.1-67. Can we update the docker tags to match that ?

@deruelle changed the wording here with commit cd4a06f , so this should be resolved.

gsaslis · 2017-12-05T08:49:55Z

@deruelle You need to update docker.

Version 3.1 is compatible with docker 1.13.1+, as indicated here: https://docs.docker.com/compose/compose-file/#compose-and-docker-compatibility-matrix

deruelle · 2017-12-05T08:53:56Z

You mean I should downgrade ? I run 17.11 now, shouldn't we expect people to run latest ?

gsaslis · 2017-12-05T09:00:41Z

@deruelle strange...
I am on

docker --version
Docker version 17.09.0-ce, build afdb6d4

and i'm not getting any errors. Let me spin up a VM and try this out... Would you mind sharing what OS / version you're on?

also, can you share the docker-compose --version output?

deruelle · 2017-12-05T10:26:06Z

jean@jean-XPS-15-9560:~/workspaces/Restcomm-Connect$ docker --version
Docker version 17.11.0-ce, build 1caf76c

Ubuntu 17.10 
jean@jean-XPS-15-9560:~/workspaces/Restcomm-Connect$ uname -r
Linux 4.13.0-17-generic

gsaslis · 2017-12-05T16:22:36Z

@deruelle Here is how i tried to reproduce:

set up new ubuntu 17.10 VM

$ vagrant init bento/ubuntu-17.10
$ vagrant up
$ vagrant ssh

Install docker manually inside the VM:

$ curl -fsSL get.docker.com -o get-docker.sh
$ sh get-docker.sh
$ docker --version
Docker version 17.11.0-ce, build 1caf76c

Install docker-compose, according to https://docs.docker.com/compose/install/

$ sudo curl -L https://github.com/docker/compose/releases/download/1.17.0/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
$ sudo chmod +x /usr/local/bin/docker-compose
$ docker-compose --version
docker-compose version 1.17.0, build ac53b73

i ran:

root@vagrant:~# docker-compose up
Starting root_restcomm_1 ... 
Starting root_restcomm_1 ... done
Attaching to root_restcomm_1
restcomm_1  | *** Running /etc/my_init.d/00_regen_ssh_host_keys.sh...
restcomm_1  | No SSH host key available. Generating one...
restcomm_1  | Creating SSH2 RSA key; this may take some time ...
restcomm_1  | 2048 SHA256:dmcxXRfRA8i5O/Rh5r/mnS1uivJXZOpoNdg56WlSotY root@1aa122a7225a (RSA)
restcomm_1  | Creating SSH2 DSA key; this may take some time ...
restcomm_1  | 1024 SHA256:CsgG8v8YRs45/9l7GQtsd7Ngyo81d8IxVoXGSOU2z6Y root@1aa122a7225a (DSA)
restcomm_1  | Creating SSH2 ECDSA key; this may take some time ...
restcomm_1  | 256 SHA256:OqH9VrmMdJ5B8/YZyRyB2Uzlrg91FyTa1WW3zOAg1GI root@1aa122a7225a (ECDSA)
restcomm_1  | Creating SSH2 ED25519 key; this may take some time ...
restcomm_1  | 256 SHA256:x8KM7hC8L+GP+bN8KVfJljfLDA4Nk39GMLZdm/6KKno root@1aa122a7225a (ED25519)
restcomm_1  | invoke-rc.d: could not determine current runlevel
restcomm_1  | invoke-rc.d: policy-rc.d denied execution of restart.
restcomm_1  | *** Running /etc/my_init.d/restcomm7.sh...
restcomm_1  |  ____            _    ____
restcomm_1  |  |  _ \ ___  ___| |_ / ___|___  _ __ ___  _ __ ___
restcomm_1  |  | |_) / _ \/ __| __| |   / _ \| '_ ` _ \| '_ ` _ \
restcomm_1  |  |  _ <  __/\__ \ |_| |__| (_) | | | | | | | | | | |
restcomm_1  |  |_|_\_\___||___/\__|\____\___/|_| |_| |_|_| |_| |_|
restcomm_1  |    | |__  _   _
restcomm_1  |    | '_ \| | | |
restcomm_1  |    | |_) | |_| |
restcomm_1  |    |_.__/ \__, |
restcomm_1  |           |___/
restcomm_1  |   _____    _           _
restcomm_1  |  |_   _|__| | ___  ___| |_ __ ___  __
restcomm_1  |    | |/ _ \ |/ _ \/ __| __/ _` \ \/ /
restcomm_1  |    | |  __/ |  __/\__ \ || (_| |>  <
restcomm_1  |    |_|\___|_|\___||___/\__\__,_/_/\_\
restcomm_1  | 
restcomm_1  | *** Running /etc/my_init.d/restcommtrace.sh...
restcomm_1  | *** Running /etc/rc.local...
restcomm_1  | *** Booting runit daemon...
restcomm_1  | *** Runit started as PID 83
restcomm_1  | tcpdump: listening on any, link-type LINUX_SLL (Linux cooked), capture size 262144 bytes

... so all works well...

any chance your .yaml might be malformed? maybe tabs vs. spaces?

deruelle · 2017-12-06T09:52:12Z

@gsaslis ok the issue was with docker-compose, I was using the sudo apt-get install docker-impose to install command it. When I followed your instructions, it worked correctly and beautifully ! Very easy and straightforward to get it to work. Much better than before IMO

Let's amend the documentation for that.

Another issue I found is with Firefox, when I call 1234 I don't get any sound and we get a 569 Unable to Setup services SIP Error back. Probably worth opening a separate issue to investigate.

…ew version

gsaslis · 2017-12-07T12:28:40Z

@deruelle added a note in the troubleshooting section and also added docker-compose in the prerequisites.

Do those address your concerns?

deruelle · 2017-12-07T18:22:06Z

Thanks @gsaslis. IMO You can go ahead and merge it. This looks good to me. One additional question, this works fine if you clone the repo but what for users that don't necessarily want to clone the repo and just run the docker image, do we still want to support that ?

gsaslis · 2017-12-11T14:04:55Z

@deruelle all they would need is the docker-compose.yml file, so they can either copy-paste the content, or pull it directly from github's raw version of the file.

gsaslis added 9 commits November 29, 2017 12:03

Some left over fixes from #2220

d395012

Were not included in #2382

Fixed outdated env var name

4e1991d

Fixed location of ENVCONFURL

91c109c

reference file had been moved to `env_files` subdir in RestComm/RestComm-Docker repo, from the `scripts` dir. fixes #2675

Removed advanced configuration guide

27d29c5

These topics are all covered in the `docker-compose.yml` file that is coming up.

Again, documentation moved to docker-compose.yml

ccde8ae

Removed guide as more advanced topic

7652b52

Environment variables are now documented in (the upcoming, hold your horses... ) `docker-compose.yml`

Migrated guides to docker compose file

320d9da

Again, documentation has been replaced / moved to the file descriptor. Also some info in the ports guide (USE_STANDARD_SIP_PORTS, USE_STANDARD_HTTP_PORTS) is now outdated

Updated quick start guide, through use of docker-compose.yml

bf92035

If you've been reading the previous commits, you *know* you've been waiting for this!!

Migrated Powermedia XMS example to docker compose script

b00ee28

deruelle reviewed Dec 5, 2017

View reviewed changes

gsaslis added 3 commits December 7, 2017 14:23

Fixed docs about docker tags, so we don't have to update with every n…

cd4a06f

…ew version

Added troubleshooting section on docker-compose @ Ubuntu 17.10

4287229

Added docker-compose as pre-requisite

4d3ba6a

Added some clarifications / explanations

6e7fec4

gsaslis merged commit 3c07943 into master Dec 11, 2017

This was referenced Dec 11, 2017

Include Restcomm XMS Documentation #1459

Closed

569 Unable to Setup Services SIP Error #2710

Open

This was referenced Dec 12, 2017

Restcomm Docker image not working on OSX 10.12.3 RestComm/Restcomm-Docker#101

Closed

Update guide on RestComm XMS configuration RestComm/Restcomm-Docker#71

Open

jaimecasero deleted the docs_improvements branch December 13, 2017 13:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs improvements #2687

Docs improvements #2687

gsaslis commented Dec 1, 2017

gsaslis commented Dec 1, 2017

gsaslis commented Dec 4, 2017

deruelle commented Dec 5, 2017

deruelle Dec 5, 2017

gsaslis Dec 7, 2017

gsaslis commented Dec 5, 2017

deruelle commented Dec 5, 2017

gsaslis commented Dec 5, 2017 •

edited

Loading

deruelle commented Dec 5, 2017

gsaslis commented Dec 5, 2017

deruelle commented Dec 6, 2017

gsaslis commented Dec 7, 2017

deruelle commented Dec 7, 2017

gsaslis commented Dec 11, 2017

Docs improvements #2687

Docs improvements #2687

Conversation

gsaslis commented Dec 1, 2017

gsaslis commented Dec 1, 2017

gsaslis commented Dec 4, 2017

deruelle commented Dec 5, 2017

deruelle Dec 5, 2017

Choose a reason for hiding this comment

gsaslis Dec 7, 2017

Choose a reason for hiding this comment

gsaslis commented Dec 5, 2017

deruelle commented Dec 5, 2017

gsaslis commented Dec 5, 2017 • edited Loading

deruelle commented Dec 5, 2017

gsaslis commented Dec 5, 2017

deruelle commented Dec 6, 2017

gsaslis commented Dec 7, 2017

deruelle commented Dec 7, 2017

gsaslis commented Dec 11, 2017

gsaslis commented Dec 5, 2017 •

edited

Loading