Commit e3387f8c authored by Nils Mittler's avatar Nils Mittler 🕵🏼
Browse files

rework windows instructions

parent 67647f08
......@@ -20,3 +20,4 @@ services:
volumes:
cards_db:
name: cards_db
......@@ -20,3 +20,4 @@ services:
volumes:
linux_cards_db:
name: linux_cards_db
......@@ -23,3 +23,4 @@ services:
volumes:
local_cards_db:
name: local_cards_db
......@@ -20,15 +20,6 @@ sudo docker-compose -f <path-to-downloaded-file> up -d
No need to clone a repository or to build anything.
As a Linux User, you can also download and run the app in one step by streaming the compose file:
```bash
# for arsnova.cards
wget -qO- projects.thm.de/compose-arsnova-cards | sudo docker-compose -f - up -d
# for linux.cards
wget -qO- projects.thm.de/compose-linux-cards | sudo docker-compose -f - up -d
```
---
**The default port for the app is Port 3000. If your Port 3000 is already in use, you may configure the forwarded Port in the downloaded docker-compose.yml file.**
......@@ -38,20 +29,11 @@ wget -qO- projects.thm.de/compose-linux-cards | sudo docker-compose -f - up -d
**To stop the app, run**
```bash
sudo docker-compose -f <path-to-docker-compose-file> stop
# or when you have streamed the compose file:
wget -qO- projects.thm.de/compose-arsnova-cards | sudo docker-compose -f - stop
# or
wget -qO- projects.thm.de/compose-linux-cards | sudo docker-compose -f - stop
```
to resume:
```bash
sudo docker-compose -f <path-to-docker-compose-file> start
# or when you have streamed the compose file:
wget -qO- projects.thm.de/compose-arsnova-cards | sudo docker-compose -f - start
# or
wget -qO- projects.thm.de/compose-linux-cards | sudo docker-compose -f - start
```
---
......@@ -59,20 +41,11 @@ wget -qO- projects.thm.de/compose-linux-cards | sudo docker-compose -f - start
**To stop the app and remove the containers, run**
```bash
sudo docker-compose -f <path-to-docker-compose-file> down
# or when you have streamed the compose file:
wget -qO- projects.thm.de/compose-arsnova-cards | sudo docker-compose -f - down
# or
wget -qO- projects.thm.de/compose-linux-cards | sudo docker-compose -f - down
```
to restart:
```bash
sudo docker-compose -f <path-to-docker-compose-file> up -d
# or when you have streamed the compose file:
wget -qO- projects.thm.de/compose-arsnova-cards | sudo docker-compose -f - up -d
# or
wget -qO- projects.thm.de/compose-linux-cards | sudo docker-compose -f - up -d
```
---
......@@ -80,20 +53,11 @@ wget -qO- projects.thm.de/compose-linux-cards | sudo docker-compose -f - up -d
**To stop the app and remove the containers and remove the volumes, run**
```bash
sudo docker-compose -f <path-to-docker-compose-file> down -v
# or when you have streamed the compose file:
wget -qO- projects.thm.de/compose-arsnova-cards | sudo docker-compose -f - down -v
# or
wget -qO- projects.thm.de/compose-linux-cards | sudo docker-compose -f - down -v
```
to restart:
```bash
sudo docker-compose -f <path-to-docker-compose-file> up -d
# or when you have streamed the compose file:
wget -qO- projects.thm.de/compose-arsnova-cards | sudo docker-compose -f - up -d
# or
wget -qO- projects.thm.de/compose-linux-cards | sudo docker-compose -f - up -d
```
---
......@@ -104,11 +68,6 @@ wget -qO- projects.thm.de/compose-linux-cards | sudo docker-compose -f - up -d
sudo docker-compose -f <path-to-docker-compose-file> pull
# or when you have streamed the compose file:
wget -qO- projects.thm.de/compose-arsnova-cards | sudo docker-compose -f - pull
# or
wget -qO- projects.thm.de/compose-linux-cards | sudo docker-compose -f - pull
# then restart the app as described as above
```
......@@ -131,7 +90,7 @@ To switch the variant, you may specify the settings file used to build the Image
**What are those Dockerfiles for?**
```bash
./Dockerfile
./.docker/develop/Dockerfile
# this Dockerfile is used to build the app locally for development
./.docker/app/Dockerfile
......@@ -158,8 +117,16 @@ To switch the variant, you may specify the settings file used to build the Image
---
## Self Build resources
If you are about to build the resources yourself or if you would like to develop on cards, you have to know git. Please make sure, you have at least passed the git webinar before proceeding.
## Developing with Docker
You can build and run the development version of cards with docker. Therefore you can use the docker-compose in the projects root directory.
1. Clone the project
2. From your project directory run `sudo UID_GID="$(id -u):$(id -g)" docker-compose up -d`\
2.1 `UID_GID="$(id -u):$(id -g)"` sets the environments variable `UID_GID` for docker-compose. This is necessary for handling correct permissions. If you do not provide it, it will use `1000` for both as default. This default value will most likely fit your system, but not with certainty.
3. This brings up the app under Port 3000 - you may change this port in the docker-compose.yml file\
3.1. The first time you run this, it may take a (long) while\
3.2. If you like to start the containers detached, use command option `-d`. Beware: you then won't see any output from the containers; at least for the first start of the app it is recommended to start the containers in foreground\
3.3. You may run the app with a custom `settings.json`-File by adding it in the docker-compose file as `command`
4. The app is now available under **localhost:\<desired-port\>**, default [localhost:3000](http://localhost:3000).
## Building production images yourself
1. Clone the project
......@@ -171,14 +138,3 @@ If you are about to build the resources yourself or if you would like to develop
2.1. If your local port 3000 is already in use, you can change it in `.docker/docker-compose.yml`\
2.2. You may also start the containers detached by using the `-d` option. Beware: you then won't see any output from the containers; at least for the first start of the app it is recommended to start the containers in foreground
3. The app is now available under [localhost](http://localhost:3000)
## Developing with Docker
You can build and run the development version of cards with docker. Therefore you can use the docker-compose in the projects root directory.
1. Clone the project
2. From your project directory run `sudo UID_GID="$(id -u):$(id -g)" docker-compose up -d`\
2.1 `UID_GID="$(id -u):$(id -g)"` sets the environments variable `UID_GID` for docker-compose. This is necessary for handling correct permissions. If you do not provide it, it will use `1000` for both as default. This default value will most likely fit your system, but not with certainty.
3. This brings up the app under Port 3000 - you may change this port in the docker-compose.yml file\
3.1. The first time you run this, it may take a (long) while\
3.2. If you like to start the containers detached, use command option `-d`. Beware: you then won't see any output from the containers; at least for the first start of the app it is recommended to start the containers in foreground\
3.3. You may run the app with a custom `settings.json`-File by adding it in the docker-compose file as `command`
4. The app is now available under **localhost:\<desired-port\>**, default [localhost:3000](http://localhost:3000).
arsnova🍅cards - Docker Instructions for Windows
arsnova🍅cards - Installing Docker under Windows via WSL 2
---
The official installation guide for **Windows Subsystem for Linux** (WSL) can be found here: [https://docs.microsoft.com/en-us/windows/wsl/install-win10](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
## Prerequisites
You must have Docker and Docker Compose installed. In most cases, Docker Compose is already included in Docker. Get it from [»here«](https://docs.docker.com/install). When using docker, make sure, you are **not** connected to any VPN.
**If you are on Win10 Home Edition, Docker Desktop won't work on your machine.** Install the docker toolbox instead: [»instructions«](https://docs.docker.com/toolbox/toolbox_install_windows/).
You need Windows 10. Older operating systems are not supported. If you are using an older Windows operating system, please use a virtual machine with Linux.
**If you are about to clone the repository** you should disable EOL-conversions in git. Otherwise git for windows will convert all LF endings to CRLF endings. This will end up in images which can not be run.
Supported Windows 10 Versions:
- For x64 systems: Version 1903 or higher, with Build 18362 or higher.
- For ARM64 systems: Version 2004 or higher, with Build 19041 or higher.
If you get an error during the installation that virtualization is not activated, it may be necessary to activate the virtualization in the firmware of your computer. With Intel e.g. `Intel-VT` or with AMD `AMD-V`.
## Installing WSL 2
Enable the WSL Feature by running following command as administrator in the PowerShell:
```bash
git config --global core.autocrlf false
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
```
Enable the Virtual Machine Platform by running following command as administrator in the PowerShell:
```bash
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
```
## Getting started (fast)
You can start using arsnova.cards or linux.cards locally by just downloading and running a docker file. In Win10 Pro, the app will be available under [localhost](http://localhost). In Win10 Home, an IP address is shown at the top of the docker toolbox - use this IP instead of localhost.
Now restart your computer.
Download the update according to your architecture:
| arch | download |
| --- | --- |
| x64 | https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi |
| arm64 | https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_arm64.msi |
Download your docker file:
- [arsnova.cards](.docker/docker-compose-cards.yml)
- [linux.cards](.docker/docker-compose-linux.yml)
Install the upgrade by double clicking the downloaded file.
Then run it with
Set the WSL 2 as default by running following command as administrator in the PowerShell:
```bash
docker-compose -f <path-to-downloaded-file> up -d
wsl --set-default-version 2
```
No need to clone a repository or to build anything.
## Installing a Linux Distro on WSL 2 via Microsoft Store
---
You can install Linux distributions from the Microsoft Store: [https://aka.ms/wslstore](https://aka.ms/wslstore).
**The default port for the app is Port 3000. If your Port 3000 is already in use, you may configure the forwarded Port in the downloaded docker-compose.yml file.**
Restart your computer after installation has finished.
---
## Installing a Linux Distro on WSL 2 manually
If you don't want to use the Microsoft Store, you can also install distributions manually.
**To stop the app, run**
We recommend Ubuntu as Linux Distribution. Download the WSL Ubuntu package according to your architecture by running following command as administrator in the PowerShell:
```bash
docker-compose -f <path-to-docker-compose-file> stop
# fisrt, switch to your home directory
cd ~
# for x64
Invoke-WebRequest -Uri https://aka.ms/wslubuntu2004 -OutFile Ubuntu.appx -UseBasicParsing
# for amd64
Invoke-WebRequest -Uri https://aka.ms/wslubuntu2004arm -OutFile Ubuntu.appx -UseBasicParsing
```
to resume:
```bash
docker-compose -f <path-to-docker-compose-file> start
When the download is finished, install the Distro by running following command as administrator in the PowerShell:
```
Add-AppxPackage .\Ubuntu.appx
```
---
Restart your computer after installation has finished.
**To stop the app and remove the containers, run**
```bash
docker-compose -f <path-to-docker-compose-file> down
## Installing Docker in your WSL 2 Distro
Now it's time to start your Linux Distro! If you have Ubuntu installed, just start the `Ubuntu` App from your start menu.
First time you start the Distro, you will be asked for a username and a password. Just take them as you like.
You now are logged in to Ubuntu. First of all, update your sources:
```
to restart:
```bash
docker-compose -f <path-to-docker-compose-file> up -d
sudo apt update
sudo apt -y dist-upgrade
sudo apt -y autoremove
```
---
Then install Docker as described in the official sources: [https://docs.docker.com/engine/install/ubuntu/](https://docs.docker.com/engine/install/ubuntu/).
**To stop the app and remove the containers and remove the volumes, run**
```bash
sudo docker-compose -f <path-to-docker-compose-file> down -v
```
to restart:
```bash
sudo docker-compose -f <path-to-docker-compose-file> up -d
sudo apt -y install \
apt-transport-https \
ca-certificates \
curl \
gnupg \
lsb-release
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
# following for x64 arch
echo \
"deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# following for arm64 arch
echo \
"deb [arch=arm64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt -y install docker-ce docker-ce-cli containerd.io
sudo curl -L "https://github.com/docker/compose/releases/download/1.28.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
```
---
Now make shure the docker daemon is autostarting with WSL. Run `sudo visudo` and add the following line:
```
%sudo ALL=(ALL) NOPASSWD: /usr/bin/dockerd
```
**To pull new image versions, run**
```bash
# first stop the app and remove containers as described above, then run
Save and close. Then run `nano ~/.bashrc` and add the following block:
```
RUNNING=`ps aux | grep dockerd | grep -v grep`
if [ -z "$RUNNING" ]; then
sudo dockerd >> ~/dockerd.log 2>&1 &
disown
fi
```
sudo docker-compose -f <path-to-docker-compose-file> pull
Save and close. Now disconnect from your WSL. From PowerShell shutdown the WSL by running:
```
wsl --shutdown
```
# then restart the app as described as above
Start the Ubuntu app and check that docker and docker-compose are running without issues:
```
sudo docker version
sudo docker-compose version
```
## Image overview
There are two stages and two variations for which you could build and run the app. All in all you will find three dockerfiles and four docker-compose in this repository. We will go into what is for what now.
## Get access to the WSL file system
**You can build/run the app in two stages: _production_ and _develop_.**
In your file browser, go to `\\wsl$\`.
The production stage will be precomiled and you will not be able to see any changes you make in the code, unless you rebuild the image. This stage is made for **using** the app and not for developing.
Here is an overview of your WSL machines. Get on your machine. You can mount your machine as a network drive with a right click, then you will always have it in the navigation bar.
The develop stage will compile the app on the fly and you will see changes immediately. This stage is made for **developing** the app.
You should store all your files for development in this drive, preferably in your home directory under `/home/<your-username>`.
**You can build/run the app in two variants: _arsnova.cards_ and _linux.cards_.**
High-performance work is only possible if you store the files in this file system! You cannot work efficiently with a shared Windows volume!
To switch the variant, you may specify the settings file used to build the Image. You may pass it to the container when creating it.
You should call all your git commands from inside the WSL.
**What are those Dockerfiles for?**
```bash
./Dockerfile
# this Dockerfile is used to build the app locally for development
If you want to work on the code with your IDE on your host, use the network drive.
./.docker/app/Dockerfile
# this Dockerfile is used to build the app locally for production
## Troubleshooting
./.docker/kaniko/Dockerfile
# this Dockerfile is needed for the automated deployment via CI - do not change it unless you know what you are doing
If you get an error `cannot connect to docker daemon` make shure, your Distro uses WSL 2! Check this by running the following from PowerShell:
```
wsl -l -v
```
**What are those docker-compose files for?**
If it says `Version 1` you can upgrade it by running `wsl --set-version <name> 2`.
---
---
---
## FROM HERE OLD STUFF ... TO BE REVIEWED
**If you are about to clone the repository** you should disable EOL-conversions in git. Otherwise git for windows will convert all LF endings to CRLF endings. This will end up in images which can not be run.
```bash
./docker-compose.yml
# starts the app for development - code changes are visible immediately
./.docker/docker-compose.yml
# builds the production image locally and starts the app
./.docker/docker-compose-cards.yml
# starts the prebuild arsnova cards app
./.docker/docker-compose-linux.yml
# starts the prebuild linux cards app
```
## Self Build resources
If you are about to build the resources yourself or if you would like to develop on cards, you have to know git. Please make sure, you have at least passed the git webinar before proceeding.
## Building production images yourself
1. Clone the project
2. From your project root directory run `docker build -f .docker/app/Dockerfile -t <your-custom-tag> .`
## Bringing up the application and self-build images automatically
1. Clone the project
2. From your project directory run `docker-compose -f .docker/docker-compose.yml up --build`\
2.1. If your local port 3000 is already in use, you can change it in `.docker/docker-compose.yml`
3. The app is now available under [localhost:3000](http://localhost:3000) or under the IP you can find at the top of the docker toolbox
## Developing with Docker
You can build and run the development version of cards with docker. Therefore you can use the standard Dockerfile in the projects root directory.
1. Clone the project
2. From your project directory run `docker-compose up`\
2.1. **This process takes a very, very long time on windows (~20min)!** Please be patient...
3. This will brings up the app under Port 3000 - you may change this port in the docker-compose.yml file\
3.1. The first time you run this, it may take a (long) while\
3.2. If you like to start the containers detached, use command option `-d`\
3.3. You may run the app with a custom `settings.json`-File by adding it in the docker-compose file as `command`
4. The app is now available under **localhost:\<desired-port\>** or under the IP you can find at the top of the docker toolbox
git config --global core.autocrlf false
```
......@@ -2,13 +2,15 @@ arsnova🍅cards
---
The [Progressive Web App](https://en.wikipedia.org/wiki/Progressive_web_app) arsnova🍅cards offers students a modern and intuitive access to one of the most successful and evidence based learning methods, i.e., [spaced repetition](https://en.wikipedia.org/wiki/Spaced_repetition).
arsnova🍅cards uses Meteor as application framework. Download and install [Meteor](https://www.meteor.com/) to get the app running in your local development environment.
arsnova🍅cards uses Meteor as application framework. For local development, you can choose the native or the containerized version with Docker.
## Hardware requirements
- 4 GB RAM
## Setup with Docker
Instructions for Docker can be found [»here«](.docker/docker_readme.md).
**This is the recommended method!**
**Instructions for starting cards with Docker can be found [»here«](.docker/docker_readme.md).**
## Setup (native)
|Step | Linux Terminal Command |
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment