Setting up the Minds stack on Windows

Over the past couple of years, I have been growing more fond of Windows as my main OS. Even for development. As a happy user of the Minds social media platform, I decided to help it grow by contributing. One way I can do this is with my time and skills. The first step in that journey is installing the Minds stack on my machine.

There is a step to update your profile script to add the minds “run-anywhere” commands. However, to have it working, you may need to update your Powershell execution policy to allow local scripts.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Now that I have my “run-anywhere” commands, I run into Docker issues on the ElasticSearch provisioning step. This happened to me before on different setups and generally was memory-related. From there, I went to check the installation troubleshooting and noticed that I hadn’t set the memory settings in sync with the installation requirements.

From there, I update my WSL configuration so that it matches these requirements.

[wsl2]
memory=8GB   # Limits VM memory in WSL 2 up to 8GB
processors=4 # Makes the WSL 2 VM use two virtual processors

However, the error persisted. Looking further down through the troubleshooting and it seems like, in case of an Elasticsearch failure, a solution is to use Hyper-V instead of WSL2 to run Docker containers. The problem is that Hyper-V isn’t part of Windows 10 Home. To use it you need to upgrade to the Professional edition. That was a whole different adventure and a painful one, read here for more details.

After upgrading, I could see the settings to update the memory and number of processors above the suggested setup requirements:

Now that it’s done I’m running the “minds install” command once more hoping this time will work. However, a few seconds in, considering the pain I went through so far, I change strategy and opt for the “no-front” option. The thought is that if setting up the whole stack takes so much time and that using that option is better for development, as mentioned in the doc, then I shall take that advice.

The installation passed the Elasticsearch creation but failed after setting up Composer and Cassandra. From there I decided to delete everything and restart from scratch. The process should be less painful now that my configuration is correct.

If you’re on Windows and Using Powershell, this is the command for you:

 rmdir minds -Recurse -Force

It will delete your Minds folder no questions asked within a minute or so. Now I’m cloning the repo again:

With a fresh repository, I run the frontend-free version of the install once more but it failed with the same monstrous error.

The first time I saw it, I thought it was a Composer error. However, it didn’t make sense since it seemed to be installed. Looking a bit closer at the error, I notice there is a clear message at the end: “/var/www/Minds/engine/vendor/Minds/Surge does not exist and could not be created.”.

With that newfound knowledge, I realise that re-cloning everything was unnecessary but started to look into how I could make this work. I ran the installer once more just because but nothing still. At this point, I decide to run the composer installer directly to figure what’s wrong and I get this:

It seems that I need a few changes here. I need to downgrade my PHP version to 7.1 and to enable some PHP extensions. Not a fan of downgrading and also I realised that the point of Docker is to run this stuff in the container. This means that even if I make it work from my machine if the container throws the same errors it’s pointless. Even better, if I run into another issue down the line people will be less able to help me due to my different setup. Eventually, I choose to run the full install again to see what happens.

Still the same, I go for the nuclear option, delete everything once more, restart the laptop and run the install command once more.

Deciding to do everything as close to right as possible, I go through the instructions once more. It seems I got everything right except for disk space. My C drive only has 10GB left when 3 are needed for the repos and 20 additional for the images and containers. I open my disk cleanup utility and see that there is about 11GB in the bin alongside 4.5GB of windows upgrade files which I can delete. On top of which I have 7GB of gaming recording in there. Generally, I move my raw gaming footage to the D drive so I do that. Then I delete the stuff reported by the disk utility cleanup and now have 28GB free. That should be just enough to move on.

Now that we took two steps back, let’s make one forward and clone the repositories once more. Once the repo is there, I run the no-front install again. However, it failed again. I look at the troubleshooting section again and the only thing that is not a mismatch is “random docker error” linked to wrong line-endings. I’m fairly sure I already set these but I do it again and redownload the repository.

Having yet another look, I can see that there is a step about sharing drives with Docker. The feature doesn’t seem to exist but I can share folders, I chose to pick the root of the C drive and to make it available to Docker. I go for it again and fail once more.

[RuntimeException]
  /var/www/Minds/engine/vendor/Minds/Surge does not exist and could not be created.

This message kept appearing and I don’t know why. At that point, I decide to raise an issue on Gitlab. Lucky for me, Gitlab offers suggestions of potentially similar issues as I type my title. There are a few tickets relating to the installation failing. In one of these, there are mentions of issues due to the submodules not pointing at their respective master branches. I stop for a moment, then decide to update my submodule branches to master and try again to install Minds.

It failed once more, same error. Now the only option I can think of without going insane or setting up Minds on another machine is opening a ticket. I do just that.

The next day I went through issues again to see if there is anything related to Windows. Outside of my ticket, I found another. That one suggests that the checkout attributes don’t apply to submodules. This would cause shell scripts to fail during the installation process. From there I decided to clear my repo and to re-clone it by explicitly setting the line break parameter in the command.

git clone --recurse-submodules --remote-submodules [email protected]:minds/minds.git --config core.autocrlf=input

Ran the command again and still nothing. Strategy switch, I decide to use Git Bash to run the commands. I go straight for the install. Still no result.

Back at the list of issues, I look for windows installation issues. Nothing open but I find one from last week which was closed. Surprisingly, it didn’t seem to have a fix but a link to another issue. A seemingly different issue with a mention of a Python 2 dependency. This prompted me to delete all my python installs and to reinstall Python 2. As you might expect, this changed nothing, the installation still fails.

From there I do some more searching around Composer and the error message I kept getting. That message could be due to some permission issues. Running PowerShell as an admin and using the sudo command didn’t work. No luck still. Then looking at the error log again, I can see an error about “Minds/Surge” but it’s not in the composer.json. Then I’m realising that the composer lock file might work just like the npm lock file. This would suggest that Composer looks up dependencies in the lock file instead of the JSON one. From there, I edit the composer.lock file and run the installer again. And it works!

Since I chose for the frontend-free installation, I still had to install the frontend separately running “npm i” in the front folder.

A few minutes and some reported vulnerabilities later it seems like I am almost ready to go. Now the last step is to manually serve that frontend. Since I am still in Powershell, I need to open a shell session from there and then serve the files.

# sh
# NODE_OPTIONS=--max_old_space_size=4096 ENGINE_PORT=8080 npm run serve:dev -- --live-reload=false

After a few minutes, I can see my local Minds stack running and can finally help out the community.

Now that it works, I will update my ticket and open a merge request to replicate the fix which opened the door for me. A door I will walk through in order to help to build Minds. Which I am starting right away by opening a merge request to push the installation fix I wrote.

Hopefully, this will be the first of many more contributions. Thank you for reading and hopefully will take inspiration to setup the Minds stack for yourself.