6 ms·

A little feedback: I want to try it (the website makes it look very clear and promising!), but the installation page [1] scared me and I almost left. Then I loo

by 037 2y ago

A little feedback: I want to try it (the website makes it look very clear and promising!), but the installation page [1] scared me and I almost left. Then I looked at the first instructions and they were for installing Docker. I know the section is named “Prerequisites,” but I was expecting just the docker-compose and some documentation on vars, given that the only way to install it is with Docker. Even the “Installation Steps” start with mkdir, cd, curl, vi, only to say “use this docker-compose.” The prerequisites can be important for many people, and there are many ways to solve this (if you think it’s a problem). One thing to remember: devs and tech-savvy people skip everything and look directly at the terminal commands/code. It’s the reason you should never insert the “don’ts” in your repository readme too high on the page: they will be the first things we’ll cut and paste :D This is not a criticism; it seems you did a wonderful job. Just the feedback of one of many dummy experimenters that you might lose on that page :) 1. https://docmost.com/docs/installation https://docmost.com/docs/installation

Lucasoato 2y ago
I would remove the instructions to install docker: people can see them in the docker documentation, it doesn’t make sense to include them somewhere else. Also I would use a .env file to manage the env variables, without requiring the user to modify the docker compose file. It’s very likely that people will version the yaml file, so it’s not a good idea to keep secrets in plaintext there. https://docs.docker.com/compose/environment-variables/set-environment-variables/ https://docs.docker.com/compose/environment-variables/set-en...
- TuringTest 2y ago
  I would not remove them, but place them elsewhere, linked from the point you should run them at the install process. It's very useful to have a complete 'getting started' page that get you from zero to working, without assuming that the reader understands what every intermediate step means. But as you said, the parts that are dependencies for other products can be encapsulated so that savvy users can skip them easily.
  - codetrotter 2y ago
    It’s better to just place links to the relevant parts of the Docker official docs if you want to help people using Docker for the first time IMO. Focus the energy of your own docs on your own product itself, and let the docs of your dependencies cover most of the general steps regarding those.
  - yencabulator 2y ago
    The instructions to install Docker are clearly wrong on many Linux distributions. They add very little value, and are yet another thing that has to be maintained.
    - Pi9h 2y ago
      The docker installation script is for Ubuntu. I added it to help some users get started pretty quickly. On the installation page, there is a link to the official Docker guide which comes first. That should help other users with an OS-specific installation guide.
- freedomben 2y ago
  I may be unusual, but I much prefer the environment variables in a docker compose file. A .env feels like an anti-pattern to me honestly.
  - Lucasoato 2y ago
    This sounds right until you have to version your docker-compose file. Storing passwords or secrets in git should be avoided; the .env file structure allows you to leave untouched the yaml file. Anybody changing it? Git pull, and you’re ready to go, since you didn’t change the yaml file and you don’t have to substitute secrets again.
    - freedomben 2y ago
      I don't disagree, but I think you're conflating secrets with environment variables. Yes most secrets are (or should be at least) passed in through env vars, but there's also a ton (in some apps 80% to 90%) of configuration that aren't secrets. I also dislike when people treat every config value as a secret. Secrets require additional overhead and care, and burdening yourself (or another dev or operator) with that in order to tweak a completely non-secretive value is unnecessary and IMHO often counterproductive. For secrets, a .env file is fine for local dev and docker-compose IMHO. The "hidden file" nature of a .env is a good fit for secrets. (For prod I prefer K8s Secrets or Vault or similar)
      - inhumantsar 2y ago
        I've had to debug by tuning multiple vars and compare the results, .env files make this a much cleaner experience especially if the CMS supports a .env file name parameter. I can keep multiple .envs and switch between them easily and know for certain that a change in behaviour isn't due to fat fingering something in the compose file. In the end it's just personal preference. I get where you're coming from.
XorNot 2y ago
IMO if you want to drive adoption you need to ship an all-in-one container. Use runit, and stick the DB, redis and your app in the same container with one nice big data directory. Because for most small teams with the ability to run containers, that's going to be all they ever need - and it means your "let's try it" experience is just `docker run <my container image>`.
- grodriguez100 2y ago
  I know this is not the recommended practice, but I am working on a legacy project where we need to migrate to Docker and the first step (before decomposing in multiple containers) would be to have an all-in-one container running all services. I am looking for hints / recommendations on the best way to do this. Can you provide any pointers ?
  - ffsm8 2y ago
    Not the person you asked, but I've done something like that several years ago, too. From alpine RUN apk add --no-cache $yourDependencies Add theSoftware /bin/theSoftware CMD rc-service yourDependency start && /bin/theSoftware You probably want to make that CMD into a bash script, produce theSoftware in another "from $yourRuntime as builderImage" and COPY from=builderImage though I'd strongly encourage you to explore the image with dive after to visualize whats been added on which command while you're changing the dockerfile https://github.com/wagoodman/dive https://github.com/wagoodman/dive I'd push back on that being a good idea though. It's okayish, but it'd be better if the software had no dependencies, falling back to file storage/embedded DB. But that's obviously scope screep, so probably not worth the effort if your chosen framework doesn't give you a drop in option for that. Basically ymmv, I wouldn't touch a software that nests multiple daemons into the same image. It's a hack for easier demos or transient starts on dev machines, but that's it. Your orm does support sqlite though, that'd probably be better then nesting a database daemon
    - grodriguez100 2y ago
      That’s useful, thanks. Will probably need to start with an Ubuntu image instead of Alpine to keep changes to a minimum. Recommendations for an “rc-service” to use in this context ?

by 037 2y ago

Lucasoato 2y ago

I would remove the instructions to install docker: people can see them in the docker documentation, it doesn’t make sense to include them somewhere else. Also I would use a .env file to manage the env variables, without requiring the user to modify the docker compose file. It’s very likely that people will version the yaml file, so it’s not a good idea to keep secrets in plaintext there. https://docs.docker.com/compose/environment-variables/set-environment-variables/ https://docs.docker.com/compose/environment-variables/set-en...

TuringTest 2y ago
I would not remove them, but place them elsewhere, linked from the point you should run them at the install process. It's very useful to have a complete 'getting started' page that get you from zero to working, without assuming that the reader understands what every intermediate step means. But as you said, the parts that are dependencies for other products can be encapsulated so that savvy users can skip them easily.
- codetrotter 2y ago
  It’s better to just place links to the relevant parts of the Docker official docs if you want to help people using Docker for the first time IMO. Focus the energy of your own docs on your own product itself, and let the docs of your dependencies cover most of the general steps regarding those.
- yencabulator 2y ago
  The instructions to install Docker are clearly wrong on many Linux distributions. They add very little value, and are yet another thing that has to be maintained.
  - Pi9h 2y ago
    The docker installation script is for Ubuntu. I added it to help some users get started pretty quickly. On the installation page, there is a link to the official Docker guide which comes first. That should help other users with an OS-specific installation guide.
freedomben 2y ago
I may be unusual, but I much prefer the environment variables in a docker compose file. A .env feels like an anti-pattern to me honestly.
- Lucasoato 2y ago
  This sounds right until you have to version your docker-compose file. Storing passwords or secrets in git should be avoided; the .env file structure allows you to leave untouched the yaml file. Anybody changing it? Git pull, and you’re ready to go, since you didn’t change the yaml file and you don’t have to substitute secrets again.
  - freedomben 2y ago
    I don't disagree, but I think you're conflating secrets with environment variables. Yes most secrets are (or should be at least) passed in through env vars, but there's also a ton (in some apps 80% to 90%) of configuration that aren't secrets. I also dislike when people treat every config value as a secret. Secrets require additional overhead and care, and burdening yourself (or another dev or operator) with that in order to tweak a completely non-secretive value is unnecessary and IMHO often counterproductive. For secrets, a .env file is fine for local dev and docker-compose IMHO. The "hidden file" nature of a .env is a good fit for secrets. (For prod I prefer K8s Secrets or Vault or similar)
    - inhumantsar 2y ago
      I've had to debug by tuning multiple vars and compare the results, .env files make this a much cleaner experience especially if the CMS supports a .env file name parameter. I can keep multiple .envs and switch between them easily and know for certain that a change in behaviour isn't due to fat fingering something in the compose file. In the end it's just personal preference. I get where you're coming from.

XorNot 2y ago

IMO if you want to drive adoption you need to ship an all-in-one container. Use runit, and stick the DB, redis and your app in the same container with one nice big data directory. Because for most small teams with the ability to run containers, that's going to be all they ever need - and it means your "let's try it" experience is just `docker run <my container image>`.

grodriguez100 2y ago
I know this is not the recommended practice, but I am working on a legacy project where we need to migrate to Docker and the first step (before decomposing in multiple containers) would be to have an all-in-one container running all services. I am looking for hints / recommendations on the best way to do this. Can you provide any pointers ?
- ffsm8 2y ago
  Not the person you asked, but I've done something like that several years ago, too. From alpine RUN apk add --no-cache $yourDependencies Add theSoftware /bin/theSoftware CMD rc-service yourDependency start && /bin/theSoftware You probably want to make that CMD into a bash script, produce theSoftware in another "from $yourRuntime as builderImage" and COPY from=builderImage though I'd strongly encourage you to explore the image with dive after to visualize whats been added on which command while you're changing the dockerfile https://github.com/wagoodman/dive https://github.com/wagoodman/dive I'd push back on that being a good idea though. It's okayish, but it'd be better if the software had no dependencies, falling back to file storage/embedded DB. But that's obviously scope screep, so probably not worth the effort if your chosen framework doesn't give you a drop in option for that. Basically ymmv, I wouldn't touch a software that nests multiple daemons into the same image. It's a hack for easier demos or transient starts on dev machines, but that's it. Your orm does support sqlite though, that'd probably be better then nesting a database daemon
  - grodriguez100 2y ago
    That’s useful, thanks. Will probably need to start with an Ubuntu image instead of Alpine to keep changes to a minimum. Recommendations for an “rc-service” to use in this context ?