-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #8 from microtechno9000/feature_wiki
Feature wiki
- Loading branch information
Showing
37 changed files
with
2,512 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 }} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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`` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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) |
Oops, something went wrong.