Documentation

• 1: Overview
• 2: Department Services
• 2.1: Content Management
• 2.2: Facilities
• 2.3: People
• 2.4: User Accounts
• 2.5: Virtualization
• 2.6: Academic Alliances
• 2.7: Durian GPGPU Server
• 2.8: Google Apps
• 3: How To
• 3.1: Command Line Basics
• 3.2: Getting Help
• 3.3: Remote Access
• 3.4: Secure Shell
• 4: ITS Services
• 4.1: Printing
• 4.2: Virtual Private Network
• 4.3: Windows Desktop Support
• 4.4: Windows Labs
• 4.5: Wireless
• 5: Tutorials
• 5.1: Multi-Bear Domicile Setup
• 5.2: Another Tutorial
• 6: Reference
• 6.1: Parameter Reference
• 7: Contribution Guidelines

1 - Overview

The Overview is where your users find out about your project. Depending on the size of your docset, you can have a separate overview page (like this one) or put your overview contents in the Documentation landing page (like in the Docsy User Guide).

Try answering these questions for your user in this page:

What is it?

Introduce your project, including what it does or lets you do, why you would use it, and its primary goal (and how it achieves it). This should be similar to your README description, though you can go into a little more detail here if you want.

Why do I want it?

Help your user know if your project will help them. Useful information can include:

• What is it good for?: What types of problems does your project solve? What are the benefits of using it?

• What is it not good for?: For example, point out situations that might intuitively seem suited for your project, but aren’t for some reason. Also mention known limitations, scaling issues, or anything else that might let your users know if the project is not for them.

• What is it not yet good for?: Highlight any useful features that are coming soon.

Where should I go next?

Give your users next steps from the Overview. For example:

• Getting Started: Get started with $project
• Examples: Check out some example code!

2 - Department Services

2.1 - Content Management

Temporary Hosting using a VM

For students doing project work, we can provide temporary virtual machines running on VMWare or Windows Hyper-V. These VMs can be configured with a web server that is visible internally to Loyola. See Virtualization for additional information.

Alternatives

We encourage those who need to set up web sites to consider establishing web hosting account via one of the many providers out there.

Blogging platforms

If you are just looking to maintain a simple site that allows for page creation and blog posts, the best options are blogging platforms, such as Wordpress, Ghost, Micro.Blog.

Linode

We actually use dedicated virtual machines for some department hosting needs. A particularly nice option is Linode. For as little as $5-$10 a month, you can get a dedicated virtual machine with any Linux distribution you like.

This option is primarily for more technical users who know Unix/Linux system administration (and commands).

Google Apps

We do have Google Apps available in the department, which includes Blogger and Google Sites. While both of these options are starting to look/feel a bit dated, they nevertheless are easy to use and require virtually no configuration (except for us to enable your site).

2.2 - Facilities

General Computing Labs

The department has general computer laboratories at the Lake Shore and Water Tower Campuses. They are three windows labs and one free/open source laboratory (at Water Tower Campus only) running Ubuntu Linux. The Windows labs are managed by Information Technology Services (ITS) with software requests submitted regularly by the department.

::: index pair: research; Internet-2 :::

Internet-2

The CS Department was part of a successful team that received funding to bring Internet-2 to Loyola University Chicago as a whole. This next-generation Internet allows students within the department to explore ideas such as cluster computing, grid computing, Internet telephony, and distributed scientific application development. In addition to Internet-2, the university maintains a high-speed optical network/ring that connects all of the Loyola campuses (LSC, WTC, and Loyola University Medical Center).

::: index pair: research; Windows HPC Cluster :::

Windows HPC Cluster

Drs. Putonti and Thiruvathukal operate two Windows HPC clusters: an 80-node dual-core Opteron cluster by Rackable Systems and a 24-node dual-core Xeon cluster by Dell. Both clusters feature high-speed Ethernet and/or Infiniband. These clusters are housed in the ITS data center.

::: index pair: research; GPGPU pair: Emerging Technologies Laboratory; GPGPU :::

GPGPU Server

Our new GPGPU Server was set up at our ETL. It is SuperServer 7046GT-TRF-TC4 with 2 x Intel Xeon Quad-Core (16 logical processors), 96GB RAM, 4 x NVIDIA® Tesla C2075 GPUs. Please read our gpgpu-server{.interpreted-text role=“doc”} guide on how to get started.

::: index single: Emerging Technologies Laboratory :::

Emerging Technologies Laboratory

The ETL is a growing presence for experimental computer science and engineering projects. This laboratory supports many experimental computing needs and is a place where students can explore ideas not covered directly in any particular class. Virtualization, embedded systems, green computing, and mobile development take place here.

::: index single: wireless :::

Wireless

The entire department (faculty offices, computer labs, emerging technologies lab, and halls) are covered by 802.11g Wireless LAN.

Research Data Center

Loyola University Chicago’s Research Data Center (RDC) is a 1,000-square-foot facility dedicated to support research and funded grants projects, provides a secure home for the computational clusters and related equipment used by our research community.

The RDC (opened in 2010) delivers a high availability computing environment for research projects. This facility is equipped with power protection, including an uninterruptible power supply and a back-up generator. Multiple computer room air conditioner (CRAC) units provide redundant cooling for the space, and a structured cabling design allows for high-speed network connectivity. In addition to fire protection, additional safety and security elements for the RDC include keycard access, camera surveillance, and environmental monitoring.

Sized to accommodate moderate growth, several research initiatives are currently taking advan- tage of the space, which at present houses three research clusters and over 100 nodes. Additionally, collaborative research efforts with other participating institutions and/or organizations have full access and connectivity to Internet2 via the Metropolitan Research & Education Network (MREN) to accommodate high bandwidth applications, data transmissions, and computational require- ments.

A steering committee, made up of senior administrators, faculty, and ITS professionals, is re- sponsible for reviewing, evaluating, and recommending strategies, plans, and policies governing the use of the RDC resources. Loyola’s RDC is managed by Information Technology Services (ITS) in partnership with the university’s Facilities Department.

Drs. Thiruvathukal, Läufer, and Putonti have a general-purpose 80-node computing cluster that runs a mix of Windows HPC Server and the ROCKS clustering software.

2.3 - People

We pride ourselves in paying attention to human interaction. While the support aliases described in the previous section must be used whenever you want something to be done, you may want to know something about the major roles in our department that are applicable to computing.

• Chairperson: Konstantin Läufer. Please contact the Chairperson with any suggestions you have for improvement, especially when itcomes to computing matters. The chairperson has the ultimate reponsibility for all department matters, especially the departmental computing budget.
• Computing Director: George K. Thiruvathukal. Pleasecontact the Computing Director with any suggestions you have for improvement or with technical support questions. The Computing Director is ultimatelyresponsible for the implementation of all computing initiatives for the department, in particular those that support our teaching and research missions.
• Lab Manager: Miao Ye. The Lab Manager is ultimately responsible for the implementation of the intiaitives as defined by the Computing Director (who consults with the Chairperson). Because there is onlyone Lab Manager at the moment, it is important to recognize that he/she works to support all requests in a timely manner but may not be ableto resolve your problem immediately. Please allow 24-48 hours for a response to any non-emergency need.
• Computing Committee: George K. Thiruvathukal (Computing Director and Committee Chair), Konstantin Läufer, Prof. Stephen Doty, and two new members to be determined (one more faculty and one more student member). The Compting Committee meets at least twice per academic year and drafts recommendations and resolutions for future computing initiatives that support the department's teaching and researchmission and those of collaborating departments. The commitee's proceedings are reported to the Chairperson.

In most cases, you should contact the Lab Manager

2.4 - User Accounts

All students and faculty are given accounts in the CS department. Your account is intended for your use only. Please change your intial password immediately on first use to improve security. (We are able to determine when a password has not been changed from the default and will lock accounts after a certain period.)

We presently lack a self-service mechanism to the PAM service maintained by ITS for resetting your password. In any event, given the manageable number of users, you can send a request to the accounts alias to have your password reset for you. Since we set up all of our accounts to match your university login ID, it is our policy to send your replacement password to your Loyola e-mail address. You may also opt to meet the lab manager in person but must show your Loyola or a government-issued id with your photo on it.

To reset your password, you should log into random.cs.luc.edu using a secure shell client (a.k.a. SSH) and use the passwd program to reset it. We recommend that you are on campus when you need to change your password.

2.5 - Virtualization

We are now able to host Xen and Windows Hyper-V virtual servers in the department. We can host these with a dedicated public IP address (justification is required to obtain one) or private IP addresses which would be visible when you connect via the Loyola VPN. Given our present resource limitations, we can only provide virtual machines on a limited basis, primarily for faculty and student research/outreach projects. Please send your requests to the vm alias (see getting-help{.interpreted-text role=“doc”}) and make sure you include the following information:

• name: your full name
• university e-mail address: we will not give virtual machines to anyone who is not part of the Loyola community, although we will allow same to be used by outsiders, provided there is a Loyola contact.
• alternate e-mail address: where we can find you in case you decide not to read your Loyola e-mail (or you're not getting your messages!)
• duration: amount of time in months for your project, or permanent (in general, permanent machines will be given only with highly sound justification.
• RAM: required RAM in 256MB increments; large allocations are rarely given. We'll prioritize requests that are smaller than 512MB.
• disk space: required storage in 10GB increments
• desired OS: We recommend Ubuntu server edition but can support many others. At present, we do not support any OS that requires a license key or activation (except Windows on our new Hyper-V racks).
• desired hostname: may be requested in one cs, math, etl, cslabs (a private zone), all of which are subdomains of luc.edu. For example, if you want the hostname gkt in the domain etl.luc.edu, you would ask for gkt.etl.luc.edu
• public or private static IP: You must say public or private. We will generally be asking you (especially if you're a student) to start with a private IP address. This in most cases will require you to choose the domain cslabs.luc.edu, which only resolves within Loyola proper.
• type of virtual machine: Xen, VMware, Hyper-V program. You would only need VMware if you want to host a Windows VM but we presently have no plans to support Windows, per our emphasis on freely available OS technology without activation requirements.
• number of CPUs: we are only able to support 1 for most requests at this time.

2.6 - Academic Alliances

The department has active memberships in various academic alliance programs:

Microsoft Developer Network (MSDN AA)

The Computer Science Department is a member of the MSDN Academic Alliance.

If you already know your login info, visit http://bit.ly/msdn-loyola-chicago-cs.

With this membership, any student who takes a computer science course will have an account to download the latest development tools, operating systems, server software, documentation, and technical references at his/her fingertips for free.

If you need to retrieve your username and password, try this:

• Username and Password: Your username is your Loyola email address. The email address must be entered in the form of xyz@luc.edu.
• Click the Sign In button on the top right. Click the button in forgot your username or password? section for a reminder. Check your Loyola email to get your password.

Please note that the MSDNAA excludes Microsoft Office. All Loyola University Chicago students have access to Microsoft Office 365. See http://www.luc.edu/its/exchange/about_office_365.shtml for details. (This does not cover faculty and staff, who need to get their own subscription.)

If you have a Mac running OS X, you can download VMware (see below) and install it. Then install Windows and other Windows applications as usual.

VMware Academic Program (VMAP)

The Computer Science Department is a member of the VMware Academic Program (VMAP).

VMware provides VMware Workstation and other virtualization products, which are helpful for users who may want to run Windows, Linux, and other operating systems on their Windows, Mac OS X, or Linux computers.

• Mac users should download VMware Fusion.
• Windows or Linux users should download VMware Workstation.

If you already know your login info, visit http://bit.ly/vmap-loyola-chicago-cs.

Apple Developer Program

The Computer Science Department is a member of the Apple Developer Progarm.

Information can be found at https://developer.apple.com/programs/ios/university/gettingstarted/.

This program requires a bit of special handling, so please contact the lab manager at people{.interpreted-text role=“doc”} to be enrolled.

2.7 - Durian GPGPU Server

The CS and Mathematics departments subscribe to Google Apps for Your

GPGPU Server

1. After you log in the server, please run the following command to install the SDK in your home directory:

   $ cp_gpusdk
   

   This will result in a folder being created in ~/NVIDIA_GPU_Computing_SDK,

2. Compiling the examples:

   $ cd ~/NVIDIA_GPU_Computing_SDK/C
   $ make
   

3. Run the deviceQuery demo to see the GPGPU device(s).

   ::: literalinclude devicequery.txt :::

4. See http://developer.download.nvidia.com/compute/cuda/3_2/docs/Getting_Started_Linux.pdf for additional details.

2.8 - Google Apps

The CS and Mathematics departments subscribe to Google Apps for Your Domain. Among other things, we can host sites, e-mail, documents, calendaring, etc. Our primary use at the moment is for Google Sites, which allows individuals, workgroups (e.g. project teams in classes), research groups, and other collaborations to host their own private or public web sites. While this software is officially in beta, it's already proving to be a winner for many needs. Moreover, we can assign you your own hostname within one of the 3 domains. Examples include www.etl.luc.edu, gkt.etl.luc.edu, doty.math.luc.edu, and tonyg.math.luc.edu.

We reserve the right to terminate any Google site that contains inappropriate content or is reported to Google or us as being offensive. So we ask that if you have such uses in mind to consider setting up your own Google Site that is not connected to LUC or the department proper. We are not generally taking advantage of e-mail and other services at this time and reserve these address for faculty and researchers officially connected to the department. To request a Google Site or other service, please see getting-help{.interpreted-text role=“doc”}.

3 - How To

3.1 - Command Line Basics

Getting Started

There are many tutorials on the web, just Google around and you will find them. A decent online tutorial is available for example at Linux.org one can also find books on Linux in a bookstore, for those who prefer a hard copy. Linux is derived from Unix, and many of its commands are identical with, or very similar to, older Unix commands. Since Apple's Mac OS X is also derived from a version of Unix (BSD Unix), many of these commands are the same as on a Mac.

Essential Commands

Typically one interacts with a Unix/Linux system using a Command Line Interface (CLI), also known as a Terminal or a Shell. Unless one is using a Desktop Manager on a Linux system, running programs (commands) is by typing on the command line. Some of the more common commands that just about everyone uses are listed below:

• pwd - "print working directory" prints the name of the current folder
• ls - list directory lists all the files in the current folder
• ls -l - long list lists the files along with permissions, creation dates, etc
• ls -A - list all files in current folder, including the hidden ones
• cd - change directory moves the current folder back to one's home folder
• cd <pathname> - change current folder to the one named by <pathname>
• cd .. - change to the parent folder of current folder
• mkdir <foldername> - make a new folder (folders are also known as directories)
• cat <filename> - prints the contents of a text file
• cat <file1> <file2> > <file3> - joins together text files <file1> and <file2> and puts the result in <file3> (cat - is short for concatenate)
• less <filename> - lets you scroll up and down through a text file; use Q to quit
• cp <file1> <file2> - makes a copy of <file1> named <file2> in the current folder; previous contents of <file2> (if any) are lost
• mv <file1> <file2> - move <file1> to <file2>; used to rename a file (previous contents of <file2> are lost)
• mv <foldername1> <foldername2> - move <foldername1> to <foldername2>; used to rename a folder name
• rm <file> - remove a file (delete it)
• rm -r * - recursively remove all files and folders in the current folder (be VERY careful with this)
• rm -r <foldername> - recursively remove the folder and all its contents, including subfolders and their files
• rmdir <foldername> - remove a folder (delete it); the folder must be empty
• man <command> - shows the manual page for the given <command>
• passwd - change your password
• lpr <filename> - print a file; should work with text, postscript, and .pdf files.
• lpq - show status of printer and print jobs
• lprm <printno> - remove a printer job from the queue
• a2ps - anything to postscript this (if installed) converts a file into postcript and then prints it; gives nicer formatting for text files
• nano - edit a text file with a user friendly interface
• pico - edit a text file (usually pico and nano are equivalent)
• nano <filename> - edit the named file
• vi <filename> - the old Unix visual editor; see the man page for help
• emacs <filename> - edit with the GNU Emacs editor; see the man page for help
• exit - quits the current Terminal session; CTRL-D often does the same
• ping <URL> - see if an IP address is answering
• who - see who is logged on
• whoami - see who you are (for the existentially challenged)
• top - show the top running processes in a list, with process numbers
• kill <number> - kill a process number (you have to own the process)
• finger <name> - show stats for the user <name>; with no <name> finger shows stats for all current users

Note that by default you are positioned in your home folder after signing in. The file system is a tree with root at /, so to view the entire file system start by typing cd followed by ls and so forth. Pathnames are separated by forward slashes, so for example a file named whosis in your home folder /home/myuserid has pathname /home/myuserid/whosis. You can always refer to files by their fully qualified pathnames, but lacking the full pathname the system will look for the file in the current folder. Note that CTRL-C often cancels the current process, and CTRL-D often serves as an End of File marker. All of the above merely scratches the surface; see external documentation for further particulars and advice.

Why learn Linux?

Because Unix and its offshoots remains one of the most important operating systems for servers, and many networking concepts are rooted in Unix for historical reasons. Because Unix/Linux systems are efficient, fast, and highly stable. Because Unix/Linux is powerful: check out wildcards, regular expressions, pipes, redirecting input and output, shell scripts, and cron jobs for starters. There are some very cool ideas here for the cognoscenti that just don't in the Windows world (or are unwieldy when transplanted there). Linux is open source software.

Trying Linux

For those who want to try it out on your personal laptop or desktop, find a decent Linux distribution such as Ubuntu, download and burn the installation CD for your hardware, and boot from the CD. This will give you a working version of Linux running from the CD (slow) that can be played with. You can also choose to install Linux on your hard drive next to the existing OS (a dual boot approach) so that you can choose the OS at boot time, or choose to install Linux in place of your existing OS.

3.2 - Getting Help

E-mail

Please direct all inquiries to Miao Ye (helpdesk@cs.luc.edu).

Microsoft Teams

Please join the Loyola CS Systems group on Loyola’s Microsoft Teams effective after Jnaury 1, 2022.
This is available to Loyola faculty, staff, and students only.

3.3 - Remote Access

All users of our systems can access their files remotely; however, we currently do not provide general support to students or faculty for Samba and CIFS shares (i.e. mounting as a Windows drive) owing largely to security and usability considerations. (There is a legacy Samba setup; however, no support is provided.) There are a number of alternatives to Windows shares that we do support and consider effective for most needs.

sshfs

If you are a Linux or Mac user, you can use the Secure Shell Filesystem client, which makes use of the Fuse project. Linux users can simply install the sshfs package (e.g., on Ubuntu: apt-get install sshfs). The Dokan project on Windows provides the same capabilities as sshfs on Linux and the Mac.

Secure FTP (sftp)

Most Secure Shell clients have the ability to upload/download files. If you are looking for something that is less transparent than a typical filesystem and can live with an upload/download model, this might be all you need (and seemingly, is what most of our users want).

Version Control Systems

We recommend that all of our students learn how to use the Concurrent Versioning System (CVS) or Subversion, especially for programming classes. Source code management is available through command-line tools or nicely integrated into many development environments, such as Eclipse and NetBeans (even Visual Studio supports Subversion through the AnkhSVN add-in). The TortoiseSVN and TortoiseHg clients for Windows are particularly nice!

Gnome and KDE

If you are an Ubuntu desktop user at home, both of these UIs allow you to connect to a remote place via SSH and browse folders as part of the UI's shell (that is, you don't need to go to the dreaded terminal). In Gnome, Places -> Connect to Server will allow a user to connect to a ssh server and will then treat that connection to your home directory like a mounted drive.

PuTTY and Cygwin

Speaking of SSH access, Windows users are encouraged to use the PuTTY or Cygwin support for SSH. There are a number of good commercial solutions but these cost big money (between $75-$100) and are not likely to be cost effective (let alone necessary) for most members of our community.

Unison

Unison is an excellent 2-way file synchronization tool. It supports all platforms.

3.4 - Secure Shell

Not all computer systems in the department are intended for general use, and some are restricted to faculty and staff usage. (And many are reserved for testing purposes.) The systems available for general use include random.cs.luc.edu and infinity.cs.luc.edu.

By default, SSH traffic (on port 22) is blocked outside of Loyola. You will need to use the VPN or the public key authentication to connect to our servers on an alternate port (22222).

For most of our user community, we think the VPN is a reasonable solution. If you don't have access, please let us know. We can get VPN access for alumni and collaborators.

Configuring SSH in General

To use public key authentication (PKA), you need to make a configuration after you install a ssh client, which includes three steps:

1. generate a private and public key pair (Key Type: RSA Key Length: 1024);
2. store private key in your local computer;
3. save public key on the remote Linux server.

In the remaining sections, we discuss different configurations that are commonly needed by faculty, staff, and students within our department.

Bitvise Tunnelier

Two Quick Steps to Configure SSH Keys Authentication With bitvise SSH client

1. Download ssh client software from http://www.bitvise.com/download-area
2. Generate a private and public key pair:

   • click the link titled 'User keypair manager' in the Login tab.

   • click the button [Generate New ...]

   • choose ssh-rsa and 1024bits

   • you can enter passphrase or leave it empty

   • click the button [Generate]

     This passphrase is not sent to the remote host, and it is only used to protect your private key. Otherwise, anyone who has access to your private key can authenticate to your account automatically.

3. Export Public key to the Linux server User keypair manager.

   • click the keypair in the slots

   • click the button [Export..]

   • chose "Export public key" and "OpenSSH format"

   • click the button [Export]

   • It should be something like:

     ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAo8q0r4d599buYHCbc36ViJniRuLvUr++asdSUh
     

   • You need to append that line to ~/.ssh/authorized_keys on the Linux server.

OpenSSH on Linux, Mac OS X, or Cygwin

1. Generate a private and public key pair

   ::: literalinclude openssh-keygen.txt :::

2. Save Public key on the Linux server

   ::: literalinclude openssh-savekey.txt :::

   You need to append that line to ~/.ssh/authorized_keys on the Linux server

3. connect to the Linux server:

   $ ssh -p port-num  xyz@server.cs.luc.edu
   

   where xyz is your username on our Linux system. The port-num and server name have been sent to your Loyola mailbox with your username and password.

PuTTY

Five Quick Steps to Configure SSH Keys Authentication With PuTTY

1. Download ssh client software:
   • Get the zip file with all PuTTY binaries http://the.earth.li/~sgtatham/putty/latest/x86/putty.zip
2. Generate a private and public key pair
   • Double click PuTTYgen.exe, press [Generate] button, keep moving mouse. Once the keys are generated, enter a passphrase for your private key, or leave the boxes empty if you do not want to protect your private key with a passphrase.
   • This passphrase is not sent to the remote host, and it is only used to protect your private key. Otherwise, anyone who has access to your private key can authenticate to your account automatically.
   • Click [Save Private key] button to save it in a file, say, C:\ppp.ppk
3. Save Public key on the Linux server

   • cut/paste your public ssh key (Please see the figure in the web page mentioned in the beginning) on ONE LINE (That is very important!!!) in a file,

   • Do not add the rsa-key-20090614 at the end. Make sure, there is ssh-rsa at the beginning.

   • It should be something like:

     ssh-rsa ... 3434343234232m/PmcZJc5uVleXfp6yJIWG5xJE9TpY1VC4n/NQlWs1PTcplk5+xhUJPHjeMkKcVMIhhUGg0l+Tt08
     

   • You need to append that line to ~/.ssh/authorized_keys on the Linux server.

4. Store Private key in PuTTY SSH authentication agent
   • Start the PuTTY SSH authentication agent PAGEANT.EXE (double click the icon).
   • After it started, right-click its syspanel icon (in the right-bottom corner of your screen)and select "add key". Select your private key file, say C:ppp.ppk, and type in your passphrase. The Pageant works as a passphrase keeper.
5. Use PuTTY to connect to the Linux server
   • Under "Host name or (IP address)" enter hostname
   • Under "Port", enter port number
   • The port number and hostname have been sent to your Loyola mailbox.
   • Then, click [Open]

This is adapted from http://www.howtoforge.com/how-to-configure-ssh-keys-authentication-with-putty-and-linux-server-in-5-quick-steps

SSH Communications

Five Quick Steps to Configure SSH Keys Authentication With ssh Client from SSH Communications

1. Download ssh client software from:

   - http://www.colorado.edu/its/docs/authenticate/printouts/win_ssh.html
   - http://www.sfsu.edu/~helpdesk/ssh/ssh329/
   

2. Generate a private and public key pair

   • In the toolbar of ssh client, there are several icons. First from left is "Save", and second is "Print". The third from RIGHT, is "Settings".
   • Click "Setting" icon.
   • In the "Setting" windows, go to "Global Settings"->"User Authentication"->"Keys".
   • Click "Keys".
   • Under "Key pair management", click "Generate New", then click Next.
   • In the "Key Generation" window that appears:
   • From the drop-down list next to "Key Type:", select RSA
   • From the the drop-down list next to "Key Length:", select 1024.
   • Click Next. The key generation process will start. When it's complete, click Next again.

3. Store private key

   • In the "File Name:" field, enter a name for the file where SSH Secure Shell will store your private key. Your public key will be stored in a file with the same name, plus a .pub extension.
   • In the boxes next to "Passphrase:", enter a passphrase for your private key, or leave the boxes empty if you do not want to protect your private key with a passphrase.
   • This passphrase is not sent to the remote host, and it is only used to protect your private key. Otherwise, anyone who has access to your private key can authenticate to your account automatically.
   • click Next, and then Finish.

4. Save Public key on the Linux server

   • Under "Public Key management", click "View". Notepad or another editor will open xxx.pub You may save it in a file. Then, you need to append that file to ~/.ssh/authorized_keys on the Linux server.

   • You may need to add ssh-rsa at the beginning of the key and edit it to make the key on one line, ex.:

     ---- BEGIN SSH2 PUBLIC KEY ----
     

     Comment: "[2048-bit rsa, cs@luc-cs-101, Thu Jul 29 2010 01:16:06]" ssh-rsa AAAAB3NzaC1yc25A4vaINWk8i8vRAYOWoPacCP8KU3NUqWExy2a6lUq75F3pYmg46cjZ8gj9aEVcGgAwGgo4XP4TBB ---- END SSH2 PUBLIC KEY ----

5. Use ssh client to connect to the Linux server

   • "Host Name:" to hostname
   • "Port Number:" to port number
   • "Authentication Method:" to Public Key.
   • The port number and hostname have been sent to your Loyola mailbox with your username and password.
   • You will be prompted for the passphrase for your private key (if you supplied one). If you did not supply a passphrasefor your private key, you will not receive a request for a passphrase when connecting to the remote host.

6. See http://kb.iu.edu/data/amzx.html for additional details. We have adapted our instructions from this page.

Cygwin SSH Installation

1. go to http://www.cygwin.com/setup.exe
   • This will download a GUI installer called setup.exe which can be run to download a complete cygwin installation via the internet.
2. Download Source
   • Please choose [Install from Internet] option, setup.exe creates a local directory to store the packages before actually installing the contents. The Root Directory for Cygwin (default C:cygwin) will become / within your Cygwin installation.
3. Choosing Packages
   • Activate the window [Select Packages]
   • enter ssh in [search] box
   • click [+] Net ...
   • click []Skip openssh ...n
   • then click [Next] .…
4. After installing Cygwin/openssh, you can configure OpenSSH for Public Key Authentication

4 - ITS Services

4.1 - Printing

Printing in the Labs

The department maintains a number of printers for its faculty, staff, and teaching/research assistants. These printers are not for general student use, and it is prohibited to print to them without permission from the department. That said, if you need to print something, in some cases we can accommodate your requests. Please contact the department secretary, Jean Rom, during normal business hours.

There are ITS-maintained Windows labs at Damen (339, 342) and Lewis Towers (LT 410/411) that use the PrintWise system. You'll need to have funds loaded on your ID to take advantage of these printers as a card swipe is required to print your document (from the PrintWise station). As with anything else in the Windows Labs, please report printing problems directly to ITS at https://heatss.it.luc.edu/HeatLDAP/.

At this time, printing is not supported from the Linux labs in LT 412 (at Water Tower Campus) and DH 341 (at Lake Shore Campus). In the interim, you will need to print from one of the adjacent Windows labs.

4.2 - Virtual Private Network

There are a number of services (read: ports) that are firewalled because they’re not secure or under persistent threats from the outside. The university VPN allows you to access these services.

There is a self-service portal via ITS at https://luc.saasit.com/.

We recommend that all students working on advanced projects to get access to the VPN so they will run into few(er) surprises.

4.3 - Windows Desktop Support

Windows Desktop Support

Windows desktop matters are handled by ITS. If you are experiencing trouble with Windows labs and other ITS issues, please open a support ticket at https://luc.saasit.com/. Linux and Mac desktop matters are the responsibility of individual faculty.

4.4 - Windows Labs

Windows Labs

With our partner, Loyola Information Technology Services (ITS), we ensure that CS and Math/Stats software needs are formally requested from ITS. This allows us to focus on advanced computing needs (in particular, Linux and server-side applications) and ensure ubiquitous access to Windows labs via the Loyola login ID.

Faculty may request additional software by visiting ITS, or by sending an e-mail to the windows alias (see getting-help{.interpreted-text role=“doc”}). In the latter case, the lab manager (Miao Ye) will fill in a software request on your behalf. You are encouraged to submit requests one month before the end of the current term, if you need the software in the summer or following term. For example, if you need software in Fall 2009, consider getting your request in by April of 2008 (one month before the Spring 2008 term ends). You should also indicate in your request whether you are willing to help test the software after it becomes available. We cannot be held responsible for late requests or requests that do not have a designated faculty member interested in testing.

Again, because the Windows hardware and software are now maintained by ITS, we ask that all issues you encounter be reported, no matter how trivial. If you discover broken hardware and/or software, use the ITS Help Desk.

4.5 - Wireless

Wireless Access

IEEE 802.11a and IEEE 802.11b/g wireless access is provided by ITS throughout the campus. See http://www.luc.edu/its/wireless.shtml for additional details.

Eduroam

Visitors to the department can join the Eduroam network.

5 - Tutorials

Tutorials are complete worked examples made up of multiple tasks that guide the user through a relatively simple but realistic scenario: building an application that uses some of your project’s features, for example. If you have already created some Examples for your project you can base Tutorials on them. This section is optional. However, remember that although you may not need this section at first, having tutorials can be useful to help your users engage with your example code, especially if there are aspects that need more explanation than you can easily provide in code comments.

5.1 - Multi-Bear Domicile Setup

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.

90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header 2

This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!

Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.

Second Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Liverpool F.C.
• Chelsea F.C.
• Manchester United F.C.

And an ordered list:

1. Michael Brecker
2. Seamus Blake
3. Branford Marsalis

And an unordered task list:

• Create a Hugo theme
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Pack bags
• ?
• Travel!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition headers are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.

Components

Alerts

Another Heading

Add some sections here to see how the ToC looks like. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

This Document

Inguina genus: Anaphen post: lingua violente voce suae meus aetate diversi. Orbis unam nec flammaeque status deam Silenum erat et a ferrea. Excitus rigidum ait: vestro et Herculis convicia: nitidae deseruit coniuge Proteaque adiciam eripitur? Sitim noceat signa probat quidem. Sua longis fugatis quidem genae.

Pixel Count

Tilde photo booth wayfarers cliche lomo intelligentsia man braid kombucha vaporware farm-to-table mixtape portland. PBR&B pickled cornhole ugh try-hard ethical subway tile. Fixie paleo intelligentsia pabst. Ennui waistcoat vinyl gochujang. Poutine salvia authentic affogato, chambray lumbersexual shabby chic.

Contact Info

Plaid hell of cred microdosing, succulents tilde pour-over. Offal shabby chic 3 wolf moon blue bottle raw denim normcore poutine pork belly.

External Links

Stumptown PBR&B keytar plaid street art, forage XOXO pitchfork selvage affogato green juice listicle pickled everyday carry hashtag. Organic sustainable letterpress sartorial scenester intelligentsia swag bushwick. Put a bird on it stumptown neutra locavore. IPhone typewriter messenger bag narwhal. Ennui cold-pressed seitan flannel keytar, single-origin coffee adaptogen occupy yuccie williamsburg chillwave shoreditch forage waistcoat.

This is the final element on the page and there should be no margin below this.

5.2 - Another Tutorial

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.

90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header 2

This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!

Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.

Second Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Liverpool F.C.
• Chelsea F.C.
• Manchester United F.C.

And an ordered list:

1. Michael Brecker
2. Seamus Blake
3. Branford Marsalis

And an unordered task list:

• Create a Hugo theme
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Pack bags
• ?
• Travel!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition headers are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.

Components

Alerts

Another Heading

Add some sections here to see how the ToC looks like. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

This Document

Inguina genus: Anaphen post: lingua violente voce suae meus aetate diversi. Orbis unam nec flammaeque status deam Silenum erat et a ferrea. Excitus rigidum ait: vestro et Herculis convicia: nitidae deseruit coniuge Proteaque adiciam eripitur? Sitim noceat signa probat quidem. Sua longis fugatis quidem genae.

Pixel Count

Tilde photo booth wayfarers cliche lomo intelligentsia man braid kombucha vaporware farm-to-table mixtape portland. PBR&B pickled cornhole ugh try-hard ethical subway tile. Fixie paleo intelligentsia pabst. Ennui waistcoat vinyl gochujang. Poutine salvia authentic affogato, chambray lumbersexual shabby chic.

Contact Info

Plaid hell of cred microdosing, succulents tilde pour-over. Offal shabby chic 3 wolf moon blue bottle raw denim normcore poutine pork belly.

External Links

Stumptown PBR&B keytar plaid street art, forage XOXO pitchfork selvage affogato green juice listicle pickled everyday carry hashtag. Organic sustainable letterpress sartorial scenester intelligentsia swag bushwick. Put a bird on it stumptown neutra locavore. IPhone typewriter messenger bag narwhal. Ennui cold-pressed seitan flannel keytar, single-origin coffee adaptogen occupy yuccie williamsburg chillwave shoreditch forage waistcoat.

This is the final element on the page and there should be no margin below this.

6 - Reference

If your project has an API, configuration, or other reference - anything that users need to look up that’s at an even lower level than a single task - put (or link to it) here. You can serve and link to generated reference docs created using Doxygen, Javadoc, or other doc generation tools by putting them in your static/ directory. Find out more in Adding static content. For OpenAPI reference, Docsy also provides a Swagger UI layout and shortcode that renders Swagger UI using any OpenAPI YAML or JSON file as source.

6.1 - Parameter Reference

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.

90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header 2

This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!

Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.

Second Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Liverpool F.C.
• Chelsea F.C.
• Manchester United F.C.

And an ordered list:

1. Michael Brecker
2. Seamus Blake
3. Branford Marsalis

And an unordered task list:

• Create a Hugo theme
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Pack bags
• ?
• Travel!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition headers are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.

Components

Alerts

Another Heading

7 - Contribution Guidelines

We use Hugo to format and generate our website, the Docsy theme for styling and site structure, and Netlify to manage the deployment of the site. Hugo is an open-source static site generator that provides us with templates, content organisation in a standard directory structure, and a website generation engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Quick start with Netlify

Here’s a quick guide to updating the docs. It assumes you’re familiar with the GitHub workflow and you’re happy to use the automated preview of your doc updates:

1. Fork the Goldydocs repo on GitHub.
2. Make your changes and send a pull request (PR).
3. If you’re not yet ready for a review, add “WIP” to the PR name to indicate it’s a work in progress. (Don’t add the Hugo property “draft = true” to the page front matter, because that prevents the auto-deployment of the content preview described in the next point.)
4. Wait for the automated PR workflow to do some checks. When it’s ready, you should see a comment like this: deploy/netlify — Deploy preview ready!
5. Click Details to the right of “Deploy preview ready” to see a preview of your updates.
6. Continue updating your doc and pushing your changes until you’re happy with the content.
7. When you’re ready for a review, add a comment to the PR, and remove any “WIP” markers.

Updating a single page

If you’ve just spotted something you’d like to change while using the docs, Docsy has a shortcut for you:

1. Click Edit this page in the top right hand corner of the page.
2. If you don’t already have an up to date fork of the project repo, you are prompted to get one - click Fork this repository and propose changes or Update your Fork to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
3. Follow the rest of the Quick start with Netlify process above to make, preview, and propose your changes.

Previewing your changes locally

If you want to run your own local Hugo server to preview your changes as you work:

1. Follow the instructions in Getting started to install Hugo and any other tools you need. You’ll need at least Hugo version 0.45 (we recommend using the most recent available version), and it must be the extended version, which supports SCSS.

2. Fork the Goldydocs repo repo into your own project, then create a local copy using git clone. Don’t forget to use --recurse-submodules or you won’t pull down some of the code you need to generate a working site.

   git clone --recurse-submodules --depth 1 https://github.com/google/docsy-example.git
   

3. Run hugo server in the site root directory. By default your site will be available at http://localhost:1313/. Now that you’re serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.

4. Continue with the usual GitHub workflow to edit files, commit them, push the changes up to your fork, and create a pull request.

Creating an issue

If you’ve found a problem in the docs, but you’re not sure how to fix it yourself, please create an issue in the Goldydocs repo. You can also create an issue about a specific page by clicking the Create Issue button in the top right hand corner of the page.

Useful resources

• Docsy user guide: All about Docsy, including how it manages navigation, look and feel, and multi-language support.
• Hugo documentation: Comprehensive reference for Hugo.
• Github Hello World!: A basic introduction to GitHub concepts and workflow.