A3: Better on-boarding experience for newcomers

[myovchev]

I've just met a confused person coming from the PHP world, who wasn't able to boot up an Apostrophe app on a local machine following the official getting started guide

I think there is a room for improvement here when it comes to meeting the system requirements and especially MongoDB and NodeJS. A typical and easy to setup environment for Linux (and I believe MacOS as well) would be docker compose and nvm.
Docker has very good installation documentation for every OS so it can be directly linked. When it comes to MongoDB a template docker-compose.yml file like this one could be embed in the docs:

version: "2"
services:
  mongo:
    image: mongo
    restart: unless-stopped
    volumes:
      - mongodb-data:/data/db
    ports:
      - "27017:27017"
    expose:
      - "27017"

volumes:
  mongodb-data:

with docker-compose up -d and docker-compose down for respectively start and stop the mongodb instance.
The nvm tool has even more simple installation procedure (via remote bash script) for *nix systems (completely in the dark about Windows development environment though, haven't do that 10+ years). The only thing left is the nvm command to download and setup as default (or via ,nvmrc project file) the correct NodeJS version.

Of course, something already discussed I guess would be a ready to go Apostrophe docker image and/or docker compose running both mongodb and the local app and while this is solid option, I think the above would be great for people to understand the semantics.

I think meeting the environment requirement is a showstopper for newcomers previously using another technologies and it would be great if they don't get stressed by that. I'll be glad to assist with whatever I can regarding the most possible simplified instructions for Linux systems (although I'm sure you have enough experience there :) )

[boutell]

Hi Miro, we've actually spent a fair amount of time working on the question of Docker for a development environment. In development, a volume for mongodb is not enough. You really want a volume for your actual code too, so you can develop your project and have it persist on your hard drive. We were looking into creating an all-purpose Docker dev environment for everyone using volumes. However the fatal flaw is that "npm install" is just incredibly slow on shared volumes when the host OS is not Linux. In general, shared Docker volumes are slow on non-Linux hosts. Good enough for persisting mongo, but terrible for "npm install" or even for apostrophe process startup (all those "require" calls). This is true even when using more relaxed syncing settings for the volume. One alternative is to run unison, but unison is a hard install on the host, which defeats the purpose of using Docker. So I created this workaround: https://github.com/boutell/docker-dev I was excited about it, because it could potentially work across platforms with no tricky installs on the host. But then I started running into fatal errors from "unison" that I could do nothing about without becoming a unison core developer (: When I google about it I see many people drawing the same conclusions. We absolutely could use Docker as a dev environment for Linux hosts only. However, Linux hosts are also the place where the instructions to just install node and mongodb on your system via the package manager are simplest. So while it might be worth it, it is not the huge win we first thought it would be. Instead, we are going in the direction of writing an Ubuntu Linux HOWTO that eventually also works, with few or no changes, on Windows Subsystem for Linux (which is also Ubuntu). MacOS would still have a separate HOWTO. But I absolutely welcome your thoughts on how we might overcome these issues in a better way. It is a hard problem. (P.S. Speaking of Docker volumes, in addition to MongoDB, in production you still need a volume for uploaded media unless you're using S3 or similar.)

…

On Wed, Jul 28, 2021 at 8:32 AM Miro Yovchev ***@***.***> wrote: I've just met a confused person coming from the PHP world, who wasn't able to boot up an Apostrophe app on a local machine following the official getting started guide <https://v3.docs.apostrophecms.org/guide/setting-up.html> I think there is a room for improvement here when it comes to meeting the system requirements and especially MongoDB and NodeJS. A typical and easy to setup environment for Linux (and I believe MacOS as well) would be docker compose and nvm. Docker has very good installation documentation for every OS so it can be directly linked. When it comes to MongoDB a template docker-compose.yml file like this one could be embed in the docs: version: "2"services: mongo: image: mongo restart: unless-stopped volumes: - mongodb-data:/data/db ports: - "27017:27017" expose: - "27017" volumes: mongodb-data: with docker-compose up -d and docker-compose down for respectively start and stop the mongodb instance. The nvm tool has even more simple installation procedure (via remote bash script) for *nix systems (completely in the dark about Windows development environment though, haven't do that 10+ years). The only thing left is the nvm command to download and setup as default (or via ,nvmrc project file) the correct NodeJS version. Of course, something already discussed I guess would be a ready to go Apostrophe docker image and/or docker compose running both mongodb and the local app and while this is solid option, I think the above would be great for people to understand the semantics. I think meeting the environment requirement is a showstopper for newcomers previously using another technologies and it would be great if they don't get stressed by that. I'll be glad to assist with whatever I can regarding the most possible simplified instructions for Linux systems (although I'm sure you have enough experience there :) ) — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#3262>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAH27PMXPW43NPKLOLHGQ3TZ72FVANCNFSM5BEIPSFQ> .

-- THOMAS BOUTELL | CHIEF TECHNOLOGY OFFICER APOSTROPHECMS | apostrophecms.com | he/him/his

[abea]

Instead, we are going in the direction of writing an Ubuntu Linux HOWTO that eventually also works, with few or no changes, on Windows Subsystem for Linux (which is also Ubuntu). MacOS would still have a separate HOWTO.

@boutell The Ubuntu hosting recipe (moving away from "howto") is now live: https://v3.docs.apostrophecms.org/cookbook/ubuntu-hosting.html. Is that what you mean to also use for local dev setup? Are you thinking of a code recipe like this for Mac and Windows setup as well? It's something to keep up with, but probably doesn't change enough to be too bad.

[boutell]

A little different. This is a production recipe. Production and development are very different animals. I was envisioning something more like our Mac recipe for development, but written with Ubuntu Linux in mind, with accompanying notes for any differences when utilizing Windows Subsystem for Linux which aims for Ubuntu compatibility.

[boutell]

BTW, was your confused person running on Windows, Linux or MacOS?

[myovchev]

@boutell Ubuntu from the screenshot. It's in the main discord channel :)

I was speaking only about development boot of Apostrophe, "trying it out" so to say. I've developed many years in a container(s). I currently prefer nvm before full docker development environment because of the performance issues you mention - there is a huge overhead even on Linux and I've spent enormous hours in writing scripts for caching docker layers, especially npm related.
My best experience now with Apostrophe (and overall with NodeJS) is virtual node JS environment via nvm and only docker mongodb container (which runs most of the time). The good thing with this is it's fast, doesn't torture my dev machine and actually the mongodb container can be used (and is used in my case) across different projects.

So let's separate topics and concentrate only on "trying out" apostrophe and not a real longterm development environment. My preferences are nvm and mongodb docker compose file. It doesn't bloat your machine with software that you don't need. It works great on Linux. It should run great on MacOS. You might ask the community about Windows - I'll pass here :)

Another idea comes from a project on A2 and one very old on Laravel. I've tried the built in VSCode docker support and it works great. The good thing here is the editor does everything for you if it has the appropriate configuration file (which is simple enough). There are ready to go configurations for NodeJS (and I believe MongoDB as well) . The user experience is great because you just need to confirm prompt on boot about open the project in container(s). And because it's Microsoft - this should work well on Windows as well. It deserves a research at least. They do for sure serious layers caching and the projects I've tried (both NodeJS and PHP) boot up extremely fast.

[boutell]

Thanks for clarifying Miro. I think we are actually not that far apart on this subject 😂

It sounds like the only real question here is whether to recommend running MongoDB in a docker container, or by installing it on the host Linux OS via the package manager. There is official documentation for that, but it does take a few steps. Docker might be easier, and running Docker commands under Windows Subsystem for Linux does appear to be a possibility, although a detour to set that up would be required.

[myovchev]

Or all the options could be present so that the user can make an (informed) decision?
Anyway, thanks for the discussion. I hope it was productive enough :)

[boutell]

Use of Docker might prevent Mongo from showing that awful "you're in WSL, abandon all hope, MongoDB is sure to explode and end life on Earth" message (and then working fine for dev purposes) (:

[myovchev]

Yes, I can confirm this happens occasionally. Never happened to me (Ubuntu), I saw it few times on my colleague laptop (MacOS). One more reason to think twice before buy a Mac.

[boutell]

Apostrophe runs great when dependencies are installed via homebrew on Mac instead, but it's not a fast Docker host, no.

…

On Thu, Jul 29, 2021 at 7:42 PM Miro Yovchev ***@***.***> wrote: Yes, I can confirm this happens occasionally. Never happened to me (Ubuntu), I saw it few times on my colleague laptop (MacOS). One more reason to think twice before buy a Mac. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3262 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAH27JBKH5ITDJ5JHPTEEDT2HRNZANCNFSM5BEIPSFQ> .

-- THOMAS BOUTELL | CHIEF TECHNOLOGY OFFICER APOSTROPHECMS | apostrophecms.com | he/him/his