Differences

This shows you the differences between two versions of the page.

--- tutorials:5 [2022/10/26 22:03] – ↷ Page moved from tutorials:5 to secret:5 tcmal
+++ tutorials:5 [2023/04/03 13:22] – created tcmal
@@ Line 1: / Line 1: @@
+====== 5. Making a custom homepage ======
+As part of your Tardis account, you get your own subdomain at ''<username>.tardis.ac'' - you can put anything (that doesn't break our rules) here, and expose whatever applications you want.
+For now, let's start by making a static homepage (one that doesn't change for each visitor). To do this, we'll create a GitLab repository, push some code to it, then add a special config that tells GitLab to make this a homepage.
+We're going to assume a little bit of familiarity with Git, but not much with GitLab. Check the links [[tutorials:4|here]] for where to learn these.
+===== Logging into GitLab and making a repository =====
+Head over to https://git.tardisproject.uk and sign in with Tardis SSO. You'll reach the home screen, which will list all the projects you have so far. Click the + in the top right, then New project/repository in the dropdown.
+We'll start with a blank project so we can learn - make sure your project name is ''<username>.tardis.ac'' so that GitLab knows we want it to be our homepage. Make sure you initialise the repository with a README.
+===== Setting up an SSH key =====
+Now we have our repository, we want to clone it locally. To do this, we need to authenticate to Gitlab in a way it understands - we'll use SSH keys because they're convenient.
+In a terminal, run ''ssh-keygen'', leaving the path at the default value. We recommend you set a passphrase - it can be anything.
+Now run ''cat ~/.ssh/id_rsa.pub'' to fetch the public part of your SSH key. Go back to GitLab, click on the icon in the top right -> preferences -> ssh keys on the left sidebar -> paste in your ssh key and hit add.
+Now we can use our SSH key to authenticate to Gitlab. Behind the scenes, this is using public-key cryptography.
+===== Cloning the repository =====
+Go back to the project you've just created and click the blue 'Clone' button. Copy the text under 'Clone with SSH' - it should look like ''git@tardisproject.uk:username/username.tardis.ac''.
+Go to your command line and type ''git clone <URL>''. Now we have a local copy of our repository that we can make changes to, then push them back up!
+===== Making a homepage =====
+For now, we're just going to make a simple homepage using HTML. Create a folder named ''public'', and inside put ''index.html'':
+<code>
+<html>
+<body>
+<h1>Hello, World!</h1>
+</body>
+</html>
+</code>
+You should come back and edit this later, adding whatever content you want.
+===== Telling GitLab it's a homepage =====
+Now we have our 'site', we need to add some special steps to make Gitlab upload and serve it for us.
+Create a new file called ''.gitlab-ci.yml'':
+<code>
+image: alpine:latest
+pages:
+  stage: deploy
+  script:
+  - echo 'Nothing to do...'
+  artifacts:
+    paths:
+    - public
+  only:
+  - main
+</code>
+If you're not familiar, this file is used to specify CI steps, which can be used for automatically testing or deploying code when it's pushed to Gitlab.
+Here, we're only defining one thing to do: 'pages', which doesn't actually do anything. We say 'public' is the output of our step, and that we only want to run it when we push to main.
+'pages' is a special name which makes Gitlab publish this, so once we commit our changes and push, it will 'build' it and then start serving. It will take a minute or two, especially the first time, but after that you're homepage will be live at <your username>.tardis.ac!
+===== More =====
+We've just used plain HTML - if this is new to you then consider learning HTML, CSS, and JS - they're the 3 languages used for websites and are both very useful to know and not that hard to learn.
+If you don't want to keep writing HTML, consider using some kind of static site generator:
+  * [[https://jekyllrb.com/|Jekyll]] is pretty common for blogs, and lets you write your main content in Markdown
+  * [[https://gohugo.io/|Hugo]] is a newer alternative similar to Jekyll
+  * [[https://astro.build/|Astro]] is a less blog-focused alternative that will be familiar to React users.
+[[https://gitlab.com/pages|Here]] are sample repositories for all of the mentioned approaches and more.
+As we've mentioned, Gitlab CI can be configured to run any command, so you could even make your own custom scripts to do this - [[https://git.tardisproject.uk/tcmal/tcmal.tardis.ac/-/tree/main/|the author's page]] uses a mix of Astro and Emacs org-mode.
+Also note that you can have multiple repositories - If you do this with a repo called ''awesome-project'' it's homepage will live at ''<username>.tardis.ac/awesome-project''.