Differences

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

--- howto:homepage [2023/07/29 11:10] – created tcmal
+++ howto:homepage [2023/09/15 10:44] (current) – Added link to next tutorial with appropriate segue andrewferguson
@@ Line 1: / Line 1: @@
-====== 5. Making a custom homepage ======
+====== 3. 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.
+If you want a static homepage (one that doesn't change for each visitor).
-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.
+===== Simple webpages =====
-===== 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.
+All you have to do is make some file in ''www/'', and it'll start being served.
-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.
+To test this, let's write some basic HTML. From your home directory:
-===== Setting up an SSH key =====
+<code>
+$ cd www/
+www/ $ nano index.html
+</code>
-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.
+This will open a simple text editor. You can use the arrow keys to move around. Now type or paste the following:
-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>
+    <head>
-<h1>Hello, World!</h1>
+        <title>My homepage</title>
-</body>
+    </head>
+    <body>
+        <h1>It Works!</h1>
+    </body>
 </html>
 </code>
-You should come back and edit this later, adding whatever content you want.
+Hit Ctrl+X then Y to save and exit. Now, if you go to ''<username>.tardis.ac'', you should see ''It Works!''. If not, you might have to wait a bit for things to propagate.
-===== Telling GitLab it's a homepage =====
+From here, you can start making your own site and putting actual content on it. If you don't know HTML/CSS, here are some good beginner resources:
-Now we have our 'site', we need to add some special steps to make Gitlab upload and serve it for us.
+  * [[https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML|Mozilla's introduction to HTML]]
+  * [[https://developer.mozilla.org/en-US/docs/Learn/CSS|Mozilla's introduction to CSS]]
+  * [[https://www.w3schools.com/html/html_intro.asp|W3School's introduction to HTML]]
+  * [[https://jgthms.com/web-design-in-4-minutes/|Web design in 4 minutes (assumes HTML+CSS knowledge)]]
+  * [[https://sadgrl.online/webmastery/|sadgrl's collection of misc resources]]
-Create a new file called ''.gitlab-ci.yml'':
-<code>
+However, editing all the HTML files by hand, on Tardis over SSH, can get a bit tedious. A static site generator (see below) reduces the amount of HTML you need to write, or go to the [[howto:files|next tutorial]] to learn about copying files to-and-from Tardis - this way you can create and edit the HTML files on your local machine, and copy them to Tardis when done.
-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.
+===== Using a static site generator =====
-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.
+Programming a site by hand is great for learning, but you might find it becomes unmanageable after a bit.
+To help, you can use a tool called a Static Site Generator (SSG), such as:
-'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
@@ Line 78: / Line 52: @@
   * [[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.
+You can install and use these from the sandbox VM, and put the output in ''www/''.
-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''.
+Alternatively, you can have your SSG run automatically, and deploy to our [[https://git.tardisproject.uk|Gitlab]] instance
+[[https://gitlab.com/pages|Here]] are sample repositories for all of the mentioned approaches and more.
+You should be familiar with Git before trying this approach.