License and Docker "re-distribution"

[arminus]

We are thinking about building the docs for one of our projects with ReType. Since everything will be Docker based and our client will need to build the documentation image/container themselves I think (due to the hardcoded url parameter), we would need to ship a Dockerfile to them which will install ReType on their premise.

Can we do that without violating any license constraints on your part?

Otherwise, I guess we'd need to retype build ourselves, commit the generated HTML to git and copy that into the container, but I don't see how that would work without us knowing on which server-domain they'll eventually run this.

[DannyBen]

That is an interesting question not only from licensing standpoint, but also from engineering standpoint.

It is a pity that some meta tags dropped upon us in the name of progress, prefer the full URL of the site - otherwise, this would not be a problem.

Wouldn't it be possible to utilize build args or environment variables to replace the domain in the static HTML?

1. Build a docker image with just the static files generated by Retype, with the domain "replace.me"
2. Use a docker build-arg to search and replace on build time
3. OR use environment variables, and have the entry point do a search and replace

[arminus]

Wouldn't it be possible to utilize build args or environment variables to replace the domain in the static HTML?

yeah, I already thought about that, too, but patching the generated HTML is rather hacky. But - if all else fails...

[arminus]

So this is what I have for now:

### STAGE 1: Build ###
FROM node AS build
RUN npm install retypeapp --global

RUN mkdir -p /usr/src/retype
RUN mkdir -p /usr/src/retype/html
WORKDIR /usr/src/retype

ARG SERVER_DOC_ADDRESS

COPY markdown ./markdown
COPY retype.yml .

# this does not work with node:14-alpine!! (-> https://github.com/retypeapp/retype/issues/122)
RUN retype build --override "{ \"url\": \"$SERVER_DOC_ADDRESS\" }"

### STAGE 2: Run ###
FROM nginx:latest

COPY --from=build /usr/src/retype/html/ /usr/share/nginx/html

[fabriciomurta]

will every client be showing the same documentation? I mean, don't you need to build it just because a different customer will have different documentation, you also need to build the same docs to different hosting targets?

[arminus]

Different deployments will have different domains. That starts internally (dev box/localhost vs. test environment) and ends externally with docs.domain-1.tld and docs.domain-2.tld.

[geoffreymcgill]

The --override build option is definitely the way to go for customizing the output on a per build basis.

retype build --override "{ \"url\": \"$SERVER_DOC_ADDRESS\" }"

The url config is not particularly a requirement of Retype, although if not provided, the sitemap.xml and some of the metatags will not be optimized as per their specs. For instance, within sitemaps.xml, the <loc> node must begin with a protocol and use consistent and fully-qualified URLs.

Here is the actual spec definition:

Attribute		Description
<loc>	required	URL of the page. This URL must begin with the protocol (such as http) and end with a trailing slash, if your web server requires it. This value must be less than 2,048 characters.

Regarding your plan to ship a Docker file referencing Retype, it is no problem at all. I don't think the existing Retype EULA explicitly prevents this form of distribution, although I can certainly see that some clarification within the EULA is required.

Please feel free to move ahead with your plan. Even re-distributing the actual executable itself would not a problem from our perspective. In fact, it would be encouraged.

At this point, the current EULA is relatively old and was written early in the life of Retype, certainly before we had a good grasp on all the scenarios in which Retype might be used. It is time for a deep review, clarification, and hopefully a significant simplification of the EULA.

Please feel free to post your question here or contact me ([email protected]) directly if you have any questions or comments and I will do my best to assist.

[geoffreymcgill]

New official Retype Docker containers published to Docker Hub. Thought you might be interested.

https://hub.docker.com/repository/docker/retypeapp/retype

We'll be working on some Docker guides and other hosting demos. It will take us some time to get those together, but we're making progress.

Let us know if you have any questions or comments and we'll do our best to assist.

Hope this helps.

[DannyBen]

Nice one @fabriciomurta - thanks for the details and context.

Of course the Retype team knows best what is the optimal way of doing things for your service, and I am just trying to provide an external point of view, as an early adopter of Retype.

Do you think we should make a zip package or an "incomplete image"

No. I don't think it is necessary.
As a long time Docker user, I have always used instructions found in Dockerfiles, to learn more about how to install things.

See the ruby image for example - this is a common practice to list all the tags, with their respective Dockerfile (when clicked).

The additional advantage of this approach, is to also allow the community to inspect how these images are built, and to propose improvements.

That said, I understand your point of view - if doing so is more complex, it may not be worth it.

Maybe we could do better with something similar to https://hub.docker.com/_/microsoft-dotnet-aspnet, so mostly Docker-related image and tags info?

Yes. I believe so. The microsoft image README example is ok, and I would view some additional docker instructions, like Mongo and Ruby and perhaps other images that are providing similar functionality to Retype (server + CLI for generation).

In general, I expect the Docker Hub README to include:

1. one short paragraph about "what is the underlying tool", with link to its homepage
2. how to use this image - providing separate use cases, with docker commands and/or sample Dockerfiles to build (like in the case of Ruby)
3. Information about the tagging/versioning policy and image variants
4. Information about mounting my own data folder (for example, a database image MUST have this instruction, since data should not be stored in the image).

We are going to work on a guide on retype.com on use cases for the Docker image

That is nice, but not an alternative. There is a saying in software design: "Help doesn't"... :)
If it needs an elaborate guide, maybe it is too complex.

You mentioned this command: docker run ... retypeapp/retype retype watch.

If you look at other Docker images, like Ruby, Mongo, Redis, Apache and Postgres (to name a few), they set their entrypoint to their app. In other words, I expect to NOT have to type "retype" again after the image name. I expect this to work: docker run -it retypeapp/retype --version

For example, in Redis:

$ docker run -it redis --version
Redis server v=6.2.6 sha=00000000:0 malloc=jemalloc-5.1.0 bits=64 build=ad7e0714ac70a86d

Now, this image can be used with ALL the use cases that retype itself can be used, without having to learn how to operate the image. If you know how to operate Retype, you are done.

This is a good opportunity to point out another reason I wanted to inspect the Dockerfile - I wanted to see which folder you are mounting, and which entrypoint you are using.

---

Anyways - of course there are many good ways of doing something, and the way you chose is not better or worse - but since I know you guys are very receptive, and since this is the "v0.0.1" of your Docker image, I thought it is my obligation to point some things out.

[fabriciomurta]

This is a good opportunity to point out another reason I wanted to inspect the Dockerfile - I wanted to see which folder you are mounting, and which entrypoint you are using.

The Dockerfile is that three-line one shown in my last post -- really! And we'll see about this entry point, that's really something that was not paid attention for. Thanks for all the points raised!

[geoffreymcgill]

Hi @DannyBen.

I expect to NOT have to type "retype" again after the image name.

How important is this for you? and/or how common is this pattern when using Docker images?

I find that pattern a little awkward. When Retype is installed using NPM or Yarn, the command prompt is returned and ready for the next command. You install and then you run the next command (retype watch).

npm install retypeapp --global
retype watch

If you are installing using a Docker image, the same pattern would be followed:

docker run -it -v $PWD:/docs -p 5000:5000 retypeapp/retype
retype watch --host 0.0.0.0

We have a plan to remove that --host 0.0.0.0 requirement. For the moment, it is required, but it will not be once we fix in the upcoming v2.3.0 release.

We're also changing the $PWD:/docs to $PWD:/retype. So, once v2.3.0 is released, the two commands to start up using the Docker image would be:

docker run -it -v $PWD:/retype -p 5000:5000 retypeapp/retype
retype watch

These of course could be combined into one command:

# Retype v2.2.0
docker run -it -v $PWD:/docs -p 5000:5000 retypeapp/retype retype watch --host 0.0.0.0

# Retype v2.3.0
docker run -it -v $PWD:/retype -p 5000:5000 retypeapp/retype retype watch

If you really wanted the retype entry point to be set, you can pass --entrypoint retype before the image name:

# Retype v2.2.0
docker run -it -v $PWD:/docs -p 5000:5000 --entrypoint retype retypeapp/retype watch --host 0.0.0.0

# Retype v2.3.0
docker run -it -v $PWD:/retype -p 5000:5000 --entrypoint retype retypeapp/retype watch

Although, that certainly doesn't clean up the command line.

Let me know what you think.

[geoffreymcgill]

We are also going to completely re-work the readme files and include copies of the docker files. Thanks for the suggestions.

[DannyBen]

You are missing my points completely.

I do not need to use Retype docker. I was pointing out common practices.

[27AR456]

Dear @geoffreymcgill we want to install retype in a Plesk Docker environment but now we do not have the possibility to map a port regarding on the docker image. Looks like the container you deploy has "Expose" option. Docker image used to deploy the container does not have "Expose" option or the required port is not exposed.

Plesk allows mapping ports that are exposed only. A feature request was created to allow specifying custom ports for containers regardless of the EXPOSED directive presence in the image.
https://plesk.uservoice.com/forums/184549-feature-suggestions/suggestions/38134906-allow-to-specify-custom-port-mapping-even-docker-i%C2%A0 Top

Please check this.

Please check the Plesk Documentation for further information about Plesk and Docker: https://docs.plesk.com/en-US/onyx/administrator-guide/plesk-administration/using-docker.75823/

Please provide ASAP a Plesk Docker Image so you can have the possibility of growing fast.

[fabriciomurta]

Hello @27AR456, just to be sure, what's your intended use of Retype Docker image with Plesk?

At first I would expect you want to host your .md documentation, so use Retype to build the docs, and then start hosting the built website as you start the container, to a mapped volume to your local hosting. Is that, by chance, correct?

[fabriciomurta]

Assuming you want to host a retype built website using Docker and Plesk, you have to build a local image with the hosting setup of your preference, upload the built image to Plesk (how to upload a Docker image FAQ in plesk website), then run it, mapping the path of Retype .md documentation path in your Plesk hosting to the container's /docs folder (see "Volume Mapping" in Plesk documentation on Docker).

For instance, if you wanted to use lighttpd to host the built website, you could build an image out of this Dockerfile:

FROM retypeapp/retype

EXPOSE 80

RUN \
  apt-get update; \
  apt-get install --yes lighttpd; \
  rm -rf /var/lib/apt/lists/*

CMD \
  retype build --output "/var/www/html"; \
  /etc/init.d/lighttpd start; \
  tail -f /var/log/lighttpd/error.log

In the case above, we kept default settings from default Retype image OS (Debian), which is, listen to port 80 and we overrode Retype to build straight to the website root, /var/www/html. In order to keep logs on screen we started lighttpd as a service and hung a command to display the log file as it updates.

If you are more comfortable with other distros, Retype also supports Ubuntu and Apline besides Debian, you can choose either from the Dockerfile's first line, respectively:

FROM retypeapp/retype:latest-ubuntu
FROM retypeapp/retype:latest-alpine

Upon changing the linux distribution potentially the RUN and CMD commands might change, as defaults and package managers may change from OS to OS (for instance, the package manager command in Alpine is apk instead of apt-get).

[DannyBen]

If indeed the purpose is to host a built retype site - why at all mix the build phase and serve phase? The output of retype is plain HTML, can be served with any static site server, and get a smaller image.

FROM nginx
COPY . /usr/share/nginx/html

If there is a need to have build and serve in the same Dockerfile, perhaps a multi-stage Dockerfile is the right solution.

[fabriciomurta]

The Dockerfile we proposed would actually be useful if it was intended to keep just the Retype project files in their plesk-driven hosting. Then every time the container is resumed it would refresh the documentation. It really boils down to the actual use case.