A web app where users can get app, theme, and icon-pack installation commands for a variety of Linux distributions. The current selection is limited to distros I personally use regularly but I would like to expand in the future.
You can view the GitHub pages deployment here
The site is intended to be above all else, clean and simple. It was developed mobile first and should be easy & pleasant to use regardless of user device. I deliberately wanted to avoid navbars and multi-page linking to keep the site as simple to use and navigate as possible. The colour scheme and fonts should suggest a 1950s retro style as I wanted a bold, bright, and vibrant (bordering on gaudy) look.
- As a Linux user I would like a simple repository of useful commands which is easy to navigate and understand.
- As a lay user the commands and instructions should be clear and easily followed.
- As a power user I want to be able to easily copy specific commands to achieve my goal of installing an app/icons/themes
The command generator concept occurred to me when I was trying to think of a project which I personally would find useful and which got me excited. As someone who frequently "distro hops" to try out different Linux distros I often have to spend time googling commands to install apps/icons/themes I regularly use because there are too many to memorize. I wanted a site that could be quickly & easily used to retrieve such commands and which I could expand in the future to include more Linux distros and obviously more apps/icons/themes.
Eventually I would like to update the site so that rather than downloading a HTML file of the commands, users can download a script to run on the specified distro which will install the selected apps/icons/themes. My knowledge of bash & shell scripts is not yet good enough to achieve this so the HTML download was a middle-ground. I would also like to impliment an "Email Commands" functionality so that users can email themselves the list of individual commands they need.
The goal of the app is to deliver specific linux commands quickly and simply, and to present them in a manner which is easy to copy & paste or download. To that end, features which may require an additional page, for example a "contact" page or "bug-report" page, were determined to be outside of the scope of this project. Likewise, a section containing summary/biographical type information about each distro was initially considered but as the intended audience would be existing linux users this was determined to be unnecessary info and thus out of scope.
The colour scheme and fonts are intended to suggest a retro 1950s style with the main title an eye catching "diner-name-at-top-of-a-menu" style. The two stylized fonts I chose for the page, (Major Mono Display and Monofett), had the desired feel but were too "busy" for use as the smaller text of the buttons/instructions. I instead used them for the section titles. Monofett was deliberately chosen for the output section as the thick black outline paired nicely with the black of the code-output area suggesting a relationship and the font harks back to old keyboard keys or screen output on a classic PC.
I wanted the distro buttons to have a bright colour so they would really stand-out and suggest that they're the main/initial point of interest. Likewise I wanted the same effect for the sidebar-trigger button once items have been added to the list. Matching that colour again on the "Add to List" button was intended to suggest a relationship between those two functions (i.e. the bright "Add to List" button transmits it's colour to the trigger button when clicked and then the Clear List button removes that colour when clicked).
The site is intentionally easy to navigate to avoid needing a navbar or page links. Clicking on a button should immediately take the user to the next step in the process. Materialize.CSS was used to make the site responsive and to enable the pleasant "flat" style design elements to keep things easy on the eyes.
- "Email Command to Me" function so users can email the command(s) they need to themselves
- "Report bug" feature for users to report if/when a command stops functioning and needs to be revisited
- A simple interface for adding more distros/apps/icons/themes which doesn't require manually adding to the distros script
LinuxCommandGenerator was developed using Visual Studio Code and GitKraken. It is hosted on GitHub pages and deployed from the master branch. Any changes committed to the master branch will automatically update on the GitHub deployment.
The project was deployed to GitHub pages by:
- Navigating to the repo page here
- Clicking on the settings tab
- Scrolling down to the "GitHub Pages" section
- Clicking on the dropdown under "Source" and selecting "master branch"
- The link to your github pages deployment will be available once the pages refreshes (it may take a few mins before the deployment itself loads correctly when you click the link)
To make a local copy of the repo on your machine:
- Create a folder in the desired location on your computer.
- Open a terminal (Mac instructions|Windows instructions|Linux instructions)
- Navigate to the folder you created using
cdcommand in terminal (e.g.cd ~/Documents/LinuxCommandGenerator) - Type
git init - Next type
git clone https://github.com/nealbrophy/LinuxCommandGenerator - To break the link between your local copy and the repo at https://github.com/nealbrophy/LinuxCommandGenerator type
git remote rm origin
To run the app locally you can:
- Double click the "index.html" file in the root directory where you cloned the repo
- Use a Visual Studio Code add-on such as Ritwick Dey's Live Server to spin run the app on a local webserver
- If you have Node.js installed you can navigate to the root folder where you cloned the repo, enter
npm install http-serverin terminal, then enternpx http-server.
- 1.) Select the name of the appropriate Linux distro.
- 2.) Select the name of the app, theme, or icon-pack you want to install.
- 3.) See the CLI commands in the output section.
- 4.) Copy to clipboard and paste into your terminal (all of these commands require super user permissions, please make sure you have this before proceeding).
- 5.) If you would like to collect multiple app/theme/icon commands, simply click the "add to list/save for later" button then continue collecting more commands as needed.
- 6.) When you have collected all the commands you need (see Step 5 above) you can download them as a nicely formatted .html file.
The project was NOT developed using TDD practices as I was not yet comfortable enough with my JS knowledge to do so. Instead I opted for end-to-end testing using Cypress.io. The tests were written to validate:
- That the page loads correctly
- That the default/start state is blank and the output & list areas were empty
- That each distro behaves as expected such that the
ouputandinstructionselements populate expected contents - That the
sidebarelement was hidden until it's trigger-button is clicked - That the "download as file" button successfully downloads a file with the name "linux-commands.html"
- First clone the repo as discribed above.
- Next make sure you have nodeJS installed (to check you can enter
node -vin a terminal window, if you get a version number then it's already installed) - if not install it
- Open Visual Studio Code and open a terminal (
Ctrl+Shift+[backtick]) - Make sure you're in the root directory of the repo (if not use the
cdcommand in terminal to navigate there) - In terminal type
npm initand fill out the fields as desired - In terminal type
npm install cypress --save-dev - Once the install process finishes, launch Cypress by typing
npx cypress open(if you run into problems check the documentation) - To execute the tests in terminal instead of opening the Cypress GUI enter
npx cypress run - When the Cypress GUI launches simply click on the name of the test script
commandGeneratorTests.spec.jsand the tests will run - The test scipt can be found in
Cypress > Integrationfolder within the root directory
In addition to the automated end-to-end tests described above the site was also rigourously tested via simple user interaction. These tests were carried out using Firefox and Chrome on a variety of Linux distributions (Elementary, Endeavour, Ubuntu, Solus) and using the in-browser developer tools. The following items were tested:
- Clicking app/icon/theme buttons prior to Distro button should present a message in the output section advising user to select a distri
- Apps/Icons/Themes which are not available for selected distro should appear as disabled/inactive
- Clicking "Copy" and "Add to list" buttons before making a valid selection should present the user with a warning message of same
- Sidebar trigger should only pulse when items are in the list and stop when the list is cleared
- Clicking "Add to List" button after selecting a NEW distro (i.e. having previously selected a distro & app) but BEFORE selecting an app for the new distro.
- Clicking "Download as file" after user has cleared the list should notify user that the list is empty.
- HTML was validated using W3C Markup Validation Service
- CSS was validated using W3C CSS Validation Service
- Colours checked for WCAG validity using Contrast Checker
- JS was validated using the Dirk Baeumer's JShint for VSC
- Copy text button presents "Copy unsuccessful" toast during cypress test but present "Copy successful" in manual testing.
- Having
scroll-behavior: smoothenabled in the stylesheet causes some Cypress tests to fail.
- If "Add To List" button was clicked after an OS had been selected but before an app had been selected the addToList function would run and add an "undefined" item to the list which would in turn be added to the sidebar and output to file.
- FIX: Add if statment to prevent addToList from running unless both distro and app/icon/theme selections had been populated and present warning msg to user if not.
- If "Add To List" button was clicked after after an app had previously been added and after a new distro had been selected bbut before a an app for the newly selected distro has been selected the previously added app would populate even though user hadn't selected it for the new distro choice.
- FIX: Reset "selection" variable to undefined every time a distro choice button is clicked.
- Clicking "Copy Code" button before anything had been selected would present confirmation that copy was successful but there was nothing to copy.
- FIX: Add if statement to check that distro and app/icon/theme selection had both been made. If not, present msg saying nothing to copy.
- Clicking "Download File" button would execute as expected but if user then opened sidebar and clicked "Download" button the same file would download even though no items were present in the saved list.
- FIX: Added final action after Download File listener executes to overwrite the dataOuput variable with an empty string.
- Copy Code functionality didn't work for the code from notSure selection. Having this ability for other code but not the code to determine which OS user is running seemed counterproductive and not great UX.
- FIX: Refactored commandGenerator script to accept notSure as valid choice for the purposes of running the copyToClipBoard and downloadFile functions. Achieved by moving the if statement (to validate distro/app selection) from within the copyToClipboard & downloadFile functions to within the click-listener "Add to List" button listener (that way statement is evaluated prior to calling addToList function and doesn't interfere with copyToClipboard/downloadFile).
- Clicking "Clear List" button would remove selections from the sidebar but NOT from the
dataOutputvariable which resulted in previously cleared entries still being downloaded despite not being in the current sidebar.- FIX: added
sideOutput = ''toclearSidebarfunction
- FIX: added
- This site uses the Materialize.CSS framework.
- This video from TheNetNinja was helpful in implementing the Materialize Tabs functionality.
- All Techs Tricks
- LinuxBabe
- FOSSLinux
- TecRobust
- ItsUbuntu
- DraSite
- LinuxHint
- AddictiveTips
- OSRadar
- ArchLinux Wiki
- suse.com
- opensuse-guide
- opensuse.org
- ScottLinux
- Dean Taylor's excellent answer on StackOverflow
- Arch, Debian, Elementary, and Ubuntu logo icons from font-logos by lukas-w
- App icons from FontAwesome
- Tux icon from Favicon.cc
Cake Bar Exercise by Codecademy
- W3Schools Color Picker and Sessions College Color Calculator were both used during this project.
- This Pinterest image was used for reference.
- Cypress in a Nutshell
- Cypress End-to-End Testing by Fireship
- Introduction to automation testing with Cypress.io by Execute Automation
- PicFlip testing write-up by AJ Greaves
- boodstrap-grid-demo deployment write-up by AJ Greaves