Skip to content

Commit

Permalink
Merge pull request #8 from microtechno9000/feature_wiki
Browse files Browse the repository at this point in the history
Feature wiki
  • Loading branch information
microtechno9000 authored Feb 29, 2024
2 parents 696d030 + a954593 commit 5e0bb9f
Show file tree
Hide file tree
Showing 37 changed files with 2,512 additions and 0 deletions.
33 changes: 33 additions & 0 deletions .github/workflows/publish-wiki.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
name: Publish ARM Wiki Update

on:
push:
branches: [main]
paths:
- arm_wiki/**
pull_request_review:
types: [submitted]
gollum:

env:
GIT_AUTHOR_NAME: Actionbot
GIT_AUTHOR_EMAIL: [email protected]

permissions:
contents: write

jobs:
job-sync-docs-to-wiki:
runs-on: ubuntu-latest
if: github.event_name != 'gollum'
steps:
- name: Checkout Repo
uses: actions/checkout@v2
- name: Sync arm docs to wiki
uses: newrelic/wiki-sync-action@main
with:
source: arm_wiki
destination: wiki
token: ${{ secrets.ARM_WIKI_TOKEN }}
gitAuthorName: ${{ env.GIT_AUTHOR_NAME }}
gitAuthorEmail: ${{ env.GIT_AUTHOR_EMAIL }}
179 changes: 179 additions & 0 deletions arm_wiki/ARM-Development-Tools.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
## Overview
To support development of ARM, some of the more tedious and repetitious development tasks have been wrapped up into the ARM Development Tools. The developer tools (devtools) are designed to help out anyone contributing to ARM and save time when testing out any changes being made.

To run devtools, navigate to the arm devtools folder and run the python file, armdevtools.py.

_Note: if the file is not executable, run `chown u+x armdevtools.py`_

`cd devtools`

## Running devtools

There are various commands available to the developer, as detailed below. The general output from the devtools follows:

```
INFO: <detail of the command being run>
INFO: Going to stop ARMUI - requesting sudo <requested to stop any ARM UI currently running>
INFO: ARM UI stopped [Ok]
INFO: -------------------------------------
INFO: <command(s) the script runs>
INFO: <Script status on running the command_ [Ok]
INFO: -------------------------------------
INFO: <command(s) the script runs>
INFO: <Script status on running the command> [Ok]
INFO: Going to restart ARMUI - requesting sudo _requested to restart the ARM UI_
INFO: ARM UI started [Ok]
```

### [-h] Help
The below shows the list of available commands devtools provides.

```
./armdevtools.py -h
usage: armdevtools.py [-h] [-b B] [-dr DR] [-db_rem] [-qa] [-pr] [-v]
Automatic Ripping Machine Development Tool Scripts
options:
-h, --help show this help message and exit
-b B Name of the branch to move to, example -b v2_devel
-dr DR Docker rebuild post ARM code update. Requires docker run script path to run.
-db_rem Database tool - remove current arm.db file
-qa QA Checks - run Flake8 against ARM
-pr Actions to run prior to committing a PR against ARM on github
-v ARM Dev Tools Version
```

### [-b B] Git branch change
Running this command provides a simple way to stop the ARM UI (if running on bare metal) and checkout a new branch. Whilst checking out a new git branch is a simple task, if the current ARM UI is not stopped prior to changing branches, strange things can occur. This script automates the change and aims to prevent spooky action at a distance.

```
./armdevtools.py -b v2_devel
INFO: Change the current git branch to - v2_devel
INFO: Going to stop ARMUI - requesting sudo
INFO: ARM UI stopped [Ok]
M arm-dependencies
Branch 'v2_devel' set up to track remote branch 'v2_devel' from 'origin'.
Switched to a new branch 'v2_devel'
INFO: ARM branch: v2_devel checked out
INFO: Going to restart ARMUI - requesting sudo
INFO: ARM UI started [Ok]
```

### [-dr DR] Docker Rebuild
Following any code changes to ARM, testing the changes in the docker image can be a tedious process. This command automates some of the process to make that change easier. To run this command, a bash script needs to be provided that will, when run will create the ARM docker image. For more details on the docker run configuration, refer to [Building ARM docker image from source](https://github.com/automatic-ripping-machine/automatic-ripping-machine/wiki/Building-ARM-docker-image-from-source)

_Note: executing this script requires docker permissions, otherwise it will fail._

Running this command executes the following docker commands.
1. Stops the ARM container
2. Removes the ARM container
3. Rebuilds the ARM container
4. Starts the ARM container, using the provided bash file/script

```
./armdevtools.py -dr /home/arm/armdocker.bash
INFO: Going to stop ARMUI - requesting sudo
INFO: ARM UI stopped [Ok]
INFO: Rebuilding docker image post ARM update
INFO: -------------------------------------
INFO: Executing: docker stop automatic-ripping-machine
Error response from daemon: No such container: automatic-ripping-machine
INFO: ARM container stopped [Ok]
INFO: -------------------------------------
INFO: Executing: docker container rm automatic-ripping-machine
Error: No such container: automatic-ripping-machine
INFO: ARM Docker container deleted [Ok]
INFO: -------------------------------------
INFO: Executing: docker build -t automatic-ripping-machine /opt/arm
Sending build context to Docker daemon 34.2MB
Step 1/21 : FROM automaticrippingmachine/arm-dependencies:1.1.1 AS base
---> 601d89529745
...
steps removed to reduce wiki size
...
Step 21/21 : WORKDIR /home/arm
---> Running in 6ed2590d5d46
Removing intermediate container 6ed2590d5d46
---> 58b643c79d04
Successfully built 58b643c79d04
Successfully tagged automatic-ripping-machine:latest
INFO: ARM Docker container rebuilt [Ok]
INFO: -------------------------------------
INFO: Executing: /home/arm/armdocker.bash
ec1f1c857f498c16f5149efaf305ed78828247577dd2c637c4c2bfd81525a449
INFO: ARM Docker container running [Ok]
INFO: Going to restart ARMUI - requesting sudo
INFO: ARM UI started [Ok]
```

### [-db_rem] Remove ARM Database
During development, there may come a time when testing requires removing the ARM database to confirm functionality and graceful exit states when no database exists. Whilst a simple command to remove the database, removing whilst ARM is running is not a good idea, again the whole spooky action at a distance. This command handles stopping the UI, removing the database and starting the UI again.

_Note: This command won't stop a docker container, and removing the ARM.db file whilst running is not a good idea._

_Note 2: Removing the arm.db file requires the user running the script to have ownership of the file, otherwise the script will fail._

```
./armdevtools.py -db_rem
INFO: Removing the ARM DB file
INFO: Going to stop ARMUI - requesting sudo
INFO: ARM UI stopped [Ok]
INFO: ARM DB /home/arm/db/arm.db removed [Ok]
INFO: Going to restart ARMUI - requesting sudo
INFO: ARM UI started [Ok]
```


### [-qa] Run Flake8 Check
When a new commit is made against ARM, the [github workflows](https://github.com/automatic-ripping-machine/automatic-ripping-machine/tree/main/.github/workflows) are automatically run against the commit, to ensure the new codes quality and functionality. Running the QA check devtool command runs the same Flake8 check against the '/opt/arm' folder and files prior to commencing any commits and potentially failing the QA checks.
For more details of how Flake8 works can be found at [https://flake8.pycqa.org/en/latest/](https://flake8.pycqa.org/en/latest/).
Running the qa check executes the below command, and if all is good will return no results, as shown below.

`flake8 /opt/arm/arm --max-complexity=15 --max-line-length=120 --show-source --statistics`

```
./armdevtools.py -qa
INFO: Going to stop ARMUI - requesting sudo
INFO: ARM UI stopped [Ok]
INFO: Running quality checks against ARM - /opt/arm
INFO: -------------------------------------
INFO: Executing: flake8 /opt/arm/arm --max-complexity=15 --max-line-length=120 --show-source --statistics
INFO: ARM QA check completed [Ok]
INFO: Going to restart ARMUI - requesting sudo
INFO: ARM UI started [Ok]
```

### [-pr] Pre-PR Actions
Executes a list of actions required to bring any ARM code up to scratch prior to raising a new PR.
Currently this runs:
- Update Git submodule (ARM dependencies)

```
./armdevtools.py -pr
INFO: Going to stop ARMUI - requesting sudo
INFO: ARM UI stopped [Ok]
INFO: Running scripts to bring ARM up to date
INFO: -------------------------------------
INFO: Executing: cd .. & git submodule update --remote
remote: Enumerating objects: 7, done.
remote: Counting objects: 100% (7/7), done.
remote: Compressing objects: 100% (7/7), done.
remote: Total 7 (delta 2), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (7/7), 3.01 KiB | 770.00 KiB/s, done.
From https://github.com/automatic-ripping-machine/arm-dependencies
* [new branch] dependabot/pip/sqlalchemy-2.0.6 -> origin/dependabot/pip/sqlalchemy-2.0.6
6caa6fb..8029c3e main -> origin/main
Successfully rebased and updated detached HEAD.
Submodule path '../arm-dependencies': rebased into '8029c3ebbe0406d07cf09e277eb17f6978986ee1'
INFO: ARM submodule updated [Ok]
INFO: Going to restart ARMUI - requesting sudo
INFO: ARM UI started [Ok]
```

### [-v] Devtools version
Reports the current version of devtools
```
./armdevtools.py -v
armdevtools.py 0.2
```
23 changes: 23 additions & 0 deletions arm_wiki/ARM-ui-skins.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
## For v2.4 or newer

ARM makes use of [Bootstrap](https://getbootstrap.com) for alot of the heavy lifting with the ARM ui. One of the benefits of using this is that it allows users to easily customise all of the ARM ui thanks to themes/skins for bootstrap.

You can get great selection of skins/Themes from here [bootswatch](https://bootswatch.com)

The process for updating the Skin/Theme is pretty simple
- Find the Theme you like
- Download its bootstrap.min.css file
- Place the file inside (arm install path)/arm/ui/static/css
- You should overwrite the previous file
- Clear your browser cache (Shift + F5 on some browsers CTRL + F5 on others)
- Thats it!


The default path for ARM unless you have changed it is `/opt/arm/`
This would mean the default full path for the bootsrap.min.css file would be `/opt/arm/arm/ui/static/css/bootstrap.min.css`

## For versions older than v2.4

Follow the above steps, there is an additional step that is required

- You will need to change the downloaded file name to bootstrap.spacelab.css and then copy it to the above directory. The only difference being that the final full path would be ``/opt/arm/arm/ui/static/css/bootstrap.spacelab.css``
3 changes: 3 additions & 0 deletions arm_wiki/ARM-workflow-diagram.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@


![Workflow Diagram](https://github.com/muckngrind4/arm_wiki/blob/master/images/arm.png)
86 changes: 86 additions & 0 deletions arm_wiki/Building-ARM-docker-image-from-source.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
## Building an ARM Docker Image

### :bangbang:This is not compatible with the snap version of docker!:bangbang:

This requires you to build an image from source.

### Pre-requisites
1. Instructions tested based on a new Ubuntu 20.04 LTS minimal install
2. Create the arm user and set a password
3. Install Docker, an editor such as Atom or VS Codium, lsscsi, and any other needed utilities as desired
4. Setup all of your optical drives so that the arm (non-root) user can mount them. Run `lsscsi -g` to verify their mountpoints if you're unsure.
-run `sudo mkdir -p /mnt/dev/sr0` and repeat for each device, e.g., sr1, sr2, etc
-edit fstab and add an entry for each drive, incrementing the sr* number for each
`sudo nano /etc/fstab`
`/dev/sr0 /mnt/dev/sr0 udf,iso9660 users,noauto,exec,utf8 0 0`

### Add the arm user and group (Recommended)
This help with permission issues, and isolates A.R.M to its own user.
```
# Create the arm group
groupadd arm
# Create the arm user
useradd -m arm -g arm
# Set the new arm users password
passwd arm
# Add the user to the cdrom,video groups
usermod -aG cdrom,video arm
```

### Build the image:
`git clone https://github.com/automatic-ripping-machine/automatic-ripping-machine.git arm`

`cd arm`

`docker build -t automatic-ripping-machine .`

### Create the container:
Remember to modify this for YOUR unique configuration!
```
docker run -d \
-p "8080:8080" \
-e ARM_UID="<id -u arm>" \
-e ARM_GID="<id -g arm>" \
-v "<path_to_arm_user_home_folder>:/home/arm" \
-v "<path_to_music_folder>:/home/arm/Music" \
-v "<path_to_logs_folder>:/home/arm/logs" \
-v "<path_to_media_folder>:/home/arm/media" \
-v "<path_to_config_folder>:/etc/arm/config" \
--device="/dev/sr0:/dev/sr0" \
--device="/dev/sr1:/dev/sr1" \
--device="/dev/sr2:/dev/sr2" \
--device="/dev/sr3:/dev/sr3" \
--privileged \
--restart "always" \
--name "automatic-ripping-machine"
```
### Finally - Open localhost:8080/setup, then login to the account

The default username and password:
username: admin
password: password

** It is strongly recommended you change this using the change password page **
A.R.M should now be fully setup, and ripping should start when a disc is inserted.

----

#### Notes
The ARM_UID(1000) and ARM_GID(1000) should exist outside the container. This helps against any permission issues.

It is recommended when passing in a device to pass in both labels you get from `lsscsi -g`
For example, if `lsscsi -g` outputs

```
[2:0:0:0] cd/dvd NECVMWar VMware SATA CD00 1.00 /dev/sr0 /dev/sg1
[32:0:0:0] disk VMware, VMware Virtual S 1.0 /dev/sda /dev/sg0
```
You should pass in
```
--device="/dev/sr0:/dev/sr0" \
--device="/dev/sg1:/dev/sg1" \
```
This isn't required, arm will still work, but it will not perform as well as it can.

### Troubleshooting
Please see the [docker troubleshooting page](https://github.com/automatic-ripping-machine/automatic-ripping-machine/wiki/Docker-Troubleshooting)
Loading

0 comments on commit 5e0bb9f

Please sign in to comment.