*written by Jeremie Bornais in June of 2023* I'm not sure what you have and haven't received so imma give you somewhat of a rundown of the situation with CSS dev stuff # GitHub Repositories *(while I encourage you to still read this section, if you're already familiar with all of our repositories and only have a limited amount of time to read this guide, you can skip this section for now)* All of our code is on our GitHub Organization: <https://github.com/uwindsorcss>. You should have been invited to join this. Here are some of our important repos: ## The Wiki: <https://github.com/uwindsorcss/wiki> This is where you'll find the code for the CSS Wiki, which is currently being hosted via GitHub pages. It automatically builds and deploys so maintenance of this should be pretty minimal. Check out the readme and the dev guide for more info ## The new CSS Site Project: <https://github.com/uwindsorcss/site> This is where you'll find the work-in-progress for the new CSS website. It's very early in development so there isn't too much to see. The plan is for the rewrite to be in Go, and that's how it's setup. However, CSS dev stuff is yours now so if you want to go in your own direction, you can decide that amongst yourselves and the execs ## The Old CSS Website: <https://github.com/uwindsorcss/hub> This is where you'll find the old CSS "hub", which is the website that's currently live at https://css.uwindsor.ca. This repository is incredibly out of date and in a state of disrepair. I challenge you to try to get it running locally (spoiler alert: you probably won't be able to). It was made using Ruby on Rails and actually is a solid website, but because we didn't keep up with updating dependencies, it became unusable. Don't bother trying to update this site instead of making a new one, it's not worth the trouble. ## The CSS Discord Bot: <https://github.com/uwindsorcss/uwindsor-discord-bot> This is the code for the Discord bot CSS uses. The master branch contains the old bot code that is currently in production. You'll be more interested in the version 2.0 branch, which is basically done and just needs to be tested before merging with master and putting into production ## Logos and Branding: <https://github.com/uwindsorcss/logos-and-branding> Here you'll find various logo files, document templates, presentation templates, etc. You probably won't ever need to edit this repository but it's super handy to have when people need our logo, logo colours, or fonts that we use. ## Important CSS Documents: <https://github.com/uwindsorcss/documents> Here you'll find our Constitution, Campaigning Regulations, and our Discord TOS. This should never be modified by you as a developer, and old ever updated by the execs or if the execs tell you to update something. The constitution is the most important document here, and can only be edited if the proposed changes are approved by motion at a CSS meeting. ## UWindsor Datasets: <https://github.com/uwindsorcss/datasets> Here you'll find a ton of datasets we've collected/scraped related to the university. It's used by the UWindsor API (found here: https://github.com/jere-mie/uwindsor-api) but feel free to continue updating it and sharing it so that people can build cool apps with UWindsor data. ## Other Misc Repositories - https://github.com/uwindsorcss/.github - contains issue templates and pull request templates which will be automatically be active across all repos in the uwindsorcss organization - https://github.com/uwindsorcss/Docs - Old developer docs that are out of date but potentially still useful - https://github.com/uwindsorcss/gate - This repository was made to encompass both the wiki and the CSS website so that they can both be brought up on our server easily. However, it never really got used. You don't need to worry about this repo very much - https://github.com/uwindsorcss/files - Here you'll find a bunch of misc files. We use this repo to upload files and share files we'd like a permalink to. DO NOT modify the paths of existing files in this repo, only ever add new files/folders. This is because old websites, videos, etc. may point to the files that you move. - The website is automatically built and hosted via github actions/pages **Other repositories probably aren't relevant to you. I wouldn't delete any of them because they may be important to other ppl on CSS or may be important for archival/historical reasons. Simply ignore them.** # Domains ## uwindsorcss.ca We own the domain `uwindsorcss.ca`. It should be paid up until 2027, so I doubt you'll need to renew it if you're reading this guide. It is owned by a namecheap account attached to `css@uwindsor.ca`. We use this domain for lots of things, so make sure to check out the namecheap DNS records. ## css.uwindsor.ca This domain is owned by the university but we have access to it for hosting our website. Definitely do not ever move the website to a different domain. We've had this domain for decades and it's important to keep it alive. Now, we don't have full access to th DNS records or anything like that. We only have the ability to host stuff on port 80 and 443 (http and https traffic) and only on the VPS provided by the university. The university **will not** let you point the domain to a different VPS outside of the university network, so you'll just have to bear with using their server. # Servers ## UWindsor VPS The first VPS you'll have access to is the VPS provided by the university and which currently hosts https://css.uwindsor.ca. You should have full sudo access (unlike the normal CS servers) and can do pretty much whatever you want with it. Be prudent though and don't screw anything up. ### SSHing into the UWindsor VPS Thanks to the university's infinite wisdom, you can't SSH into this server like normal. You need to first use the GlobalProtect VPN to SSH into the CS servers, then from the CS servers SSH into the css.uwindsor.ca server. Jeremie can add your SSH key and give you creds to SSH into this server. ### Server Configuration We currently use Caddy as the reverse proxy for our website (meaning caddy translates requests to css.uwindsor.ca to the actual hub website). You can see the (very simple) config by checking out `~/Caddyfile`. The hub and discord bot are both systemd services, and can be started/stopped easily. ## GCP Server In addition to the UWindsor VPS, we also have a VPS which is provided to us for free by GCP. If you're not aware, GCP has an always-free tier for their lowest power VPS. Currently, the only thing running on this VPS is, I believe, the UWindsor API (https://github.com/jere-mie/uwindsor-api). However, right now I believe the server is down because the credit card information changed. You'll need to have Abbie update the info to regain access. If you're wondering why we would have a secondary server in addition to the one provided to us by the university, it's because the university's server is not very reliable, and having a back-up is a good idea. Also, in the future, the database for the new website should NOT be hosted on the University server, so this server is an option. (I can touch on this more later). # Next Steps for You as Head of Tech The first thing you should do is familiarize yourself with all of the repositories I mentioned above. Going over the source code briefly for each of them will help give you more insight into the stack you're going to be working with. Other than this, there are two main tasks you should begin tackling immediately: 1. Making the new CSS website 2. Getting the new Discord bot rewrite into production The second one shouldn't take too long, you'll just need to do some testing and get everything merged, but the first one is probably more important. # The New CSS Website The most important project for you as of now is the CSS website rewrite. As I mentioned above, the current website is in a state of disrepair and a rewrite is needed. Over the past bit, Ryan and I have put together a skeleton for the new website, which can be found here: https://github.com/uwindsorcss/site. ## Why Golang? You may have noticed we used golang for the new site. Now, CSS dev stuff is yours now and you can choose to go with a different option if you find it works better for you, however there are some important reasons why we chose golang for the website rewrite. The main reason why we chose go is because we didn't want a repeat of what happened with the current CSS website. Go supports vendoring of dependencies, building static binaries with embedded config files, and a some other stuff that make it a lot more reliable than other options. Vendoring of dependencies means that we save a copy of the packages we depend on alongside our sourcecode. This means when you download a copy of the repository, you don't need to go and install additional packages, as they're already included in the repository. This means even if the developer stops supporting/hosting a package we use, we'll still be able to use it in our application. One of the issues with the current CSS website is that some of the dependencies legitimately cannot be downloaded anymore. Vendoring helps to fix this. Building static binaries with embedded config files is another extremely useful feature of go that makes it stand out among other options. This essentially means the website can be build into one executable file without the need for any other static files or configs. This means even if for whatever reason dependencies couldn't be installed or setting up a local development environment was difficult, you would still be able to get the website up and running by downloading and running one of the built binary files. In addition to these reasons, Go is also very fast and efficient, meaning our website can run blazing fast on very limited hardware. ### How Important Are These Things? The reasons I've mentioned clearly demonstrate how Go is well suited for this project, and can help to prevent future CSS dev teams from having to rewrite the site like you are now. However, I do recognize that you are your own team and you have your own set of skills and objectives. If going with Go means you have to significantly sacrifice on development time and features, then I would understand why you would choose to go with another option. Talk with your exec team about priorities and what the best option is going forward. From a tech/development perspective, Ryan and I are of the opinion that Go is the best option. From a business perspective, however, that is for you and your exec team to assess. **My final word of advice on this manner is to just make sure you choose the tech stack carefully, as the code you're working on now will affect 100s (potentially 1000s) of students for years to come, and will need to be maintained or replaced by teams other than yourself.** ## Ok, Golang Sermon Over Regardless of what tech stack you choose, you'll still need a base set of features for the new site: 1. Discord Authentication 2. Event Managemet 3. Content Management 4. Analytics I'll go over these a bit more in detail: ### Discord Authentication Depending on how long it's been since you joined the server, you may or may not remember how we handle new members joining. Possibly the most important thing about the CSS server is that it's **student only**. The only way we can reliably achieve this is by **not using Discord invites** and instead using a custom authentication system using OAuth. It's extremely important that this student-only nature is upheld. Allowing profs into the server would have serious detrimental effects on students, as they would no longer have a safe place to talk without fear of profs or staff seeing what they say. (and no, this does not mean we condone cheating on our server, as I'm sure you're already aware) Basically, the way it works is that UWindsor students sign in on our website using Microsoft's OAuth. We use OAuth to restrict who can sign in to UWindsor accounts, and then further restrict it to only UWindsor students using a **professor/staff email blacklist** and also seeing what a user's status is (student, staff, etc.) Once a user is authenticated via OAuth, if this is their first time signing in we create an account for them on our database, and simply sign them in otherwise. From there, we let users sign in/authorize with Discord's OAuth API, which allows us to add them to the CSS Discord server. Finally, we also update the user's name to their real name, which we can easily grab from the OAuth response when they sign in. #### Some Quirks With Discord Authentication One common issue that users have is that they accidentally sign into the wrong Discord account, adding the wrong one to the CSS server. Since only one Discord account should be linked to one UWindsor email (to prevent people from working around bans or allowing profs in), you should do the following when a user wants to switch their Discord account: 1. Remove their old Discord account from the CSS server 2. Update the database to remove the link between the user's Discord account and UWindsor email - Depending on how you have your database schema set up, you may do this in a variety of ways - Since this is a common thing you'll be doing throughout the school year, you may want to add this as a feature for admin users on the website, that way you don't have to log into the VPS or deal with any funny business to update things 3. Ask them to redo the sign up process on the website. - If you updated the database appropriately, this should work for them ### Event Management Depending on whether or not you've attended many CSS events in person, you may be familiar with the CSS events page (https://css.uwindsor.ca/events). Admins on the CSS website can create and edit events, which users can then sign up for (go ahead and try making one!) This is obviously less important than the Discord Authentication feature, but this is still an important feature nonetheless. It helps us easily create and share events and restrict them to UWindsor students. ### Content Management All the other pages on the CSS website can be edited by admin users without having to change any code (you should be able to see this when you're logged in). This is important to include in the new CSS website because executives shouldn't need to edit the source code of the website just to change the content of it. Making our website like a CMS will allow content changes to propagate instantly without the need for redeployment or PR reviews. Again, this isn't as important as authentication so a V1 of the new website can probably do without it, but I highly highly recommend working on and including this. ### Analytics I won't speak on this much, but knowing what kind of traffic we get on our website is nice to have and easy to setup. The current website uses Google Analytics but you can explore whatever options you want (hell, maybe even a custom middleware or smth if you really wanna get adventurous lol). # Your Other Duties as Head of Tech Here's just a small list of other stuff you're going to need to work on as Head of Tech, in addition to creating the new site and getting the Discord rewrite merged: - Maintain the CSS Wiki - This involves reviewing PRs as well as actively adding new articles and features - Give tech support to people trying to join the Discord server - Sometimes weird things can happen and our tech doesn't work as it should - when this happens you'll need to be prepared to help troubleshoot students trying to join our server. - Monitor the website/Discord bot and bring it back online - Remember when I said the University's servers weren't reliable? Well - it's a not-uncommon occurence for our server to randomly shut down, and sometimes we need to bring our website and bot back online. - I'm pretty sure they're supposed to automatically go back online but sometimes things don't work out as they're supposed to. - Manage the CSS Dev Team - How you organize your dev team (how many devs, how you recruit devs, what each person works on, etc.) is up to you - Simply put though, we normally recruit some students to help out with our current projects (especially the wiki) - Talk to your executive team to coordinate # Closing Advice The job you're doing now and the projects you're working on will undoubtedly have a profound impact on a large number of students. Just our Wiki alone is visited by most CS students coming into the program at one time or another. Thus, **take pride in the work you do** and take this position seriously. When you see the impact you have on others I'm sure you'll be immensely satisified with yourself 🙂 ## Balance Productivity and Reliability While you should take pride in the work you do and strive to create great software, recognize that if over-engineering a project is costing you too much time, it may be worth spending less time trying to make it perfect. No software you write will ever be perfect, and even perfect software is of no use to anyone if it's never released. Therefore, try to find a balance between making good software from a developer standpoint and creating products in a timely manner which users will appreciate. ## UWindsor IT is a Mess Dealing with university administration, especially ITS, is and always will be a pain. Understand that some things may need to be hacked together or done on your own (within reason) as opposed to getting official support from ITS. As a word of advice, deal with CSIT instead of ITS whenever you can. CSIT it the IT organization for the School of Computer Science, whereas ITS is for the entire university. ### CSIT CSIT maintains the domain `cs.uwindsor.ca`, the CS Servers (NoMachine), the MyWeb servers, the Electron server, and our server. If you need help with anything regarding those, CSIT is who you should talk to. If you're not sure whether something is for CSIT or ITS, try CSIT first since they'll be much more likely to respond. Our main contact with CSIT is Robert Mavrinac (though I believe he either has retired or is retiring soon). If you have issues contacting Robert, talk to Margaret and she should be able to point you in the right direction. ### ITS ITS manages everything IT related for the University that CSIT doesn't. The biggest thing you'll need from them is networking and firewall stuff for our `css.uwindsor.ca` domain. Although our server is maintained by CSIT, ITS is responsible for the firewall. Thus, if you need to open any additional ports, you'll need to contact them. ITS can't be contacted via email, and you'll need to make a ticket if you ever want to talk with them (or do their online chat thing). In my experience, the ticketing system is pretty hit or miss - sometimes they're quick and helpful, other times they're not helpful, and other times they don't even respond to your ticket. If you can't get through to someone you can try their online chat feature, but I've never tried it so I can't comment on how well that works. The only other option you have for contacting them is by finding a specific person in ITS and emailing their personal UWindsor email. This doesn't always work though and you need to know who to talk to ahead of time - so it's not really the best option.