The repo for the Carberra website.
This contains all of the information and specifics on the tech stack that the project uses.
Item | Value |
---|---|
Language | Typescript |
Package Manager | Yarn |
Server | Node.JS |
Framework | Next JS (React) |
Preview | Storybook |
CSS Processor | PostCSS |
Analytics/Stats | Plausible |
API | Next JS API Routes |
Name | Use |
---|---|
TailwindCSS | Styling from HTML via classes |
Axios | API requests |
Material UI (core, icons, and styles) | Nice, pre-made components to speed up development |
Node Mailer | Send emails for contact form |
React Markdown | Render markdown on pages |
Gray Matter | Interpret and parse markdown files |
SASS | Use SASS/SCSS for styling |
Babel (core) | Part of Storybook |
Name | Use |
---|---|
Babel Loader | Part of storybook |
SVGR/Webpack | Loading svgs via webpack |
PostCSS Loader | Load PostCSS in Storybook |
SASS Loader | Load SASS in Storybook |
TSConfig Paths Webpack Plugin | Support TS path aliases in Storybook |
Auto Prefixer | PostCSS plugin to add CSS prefixes |
Tailwind Children (plugin) | TailwindCSS plugin to allow styling child components |
Name | Use |
---|---|
Actions, Essentials, Links | Automatically installed with Storybook |
PostCSS | Allow for loading of PostCSS |
Builder, Manager (Webpack 5) | Use Webpack 5 to be consistent with main app |
Theming | Add dark mode (essential) |
Name | Use |
---|---|
Remark GFM | Add GitHub style markdown support (such as tables) |
Remark Slug | Add linking to markdown headers |
Rehype Raw | Process HTML tags within markdown |
Directory | Description |
---|---|
src | Main codebase |
public | The files that are publicly accessable |
scripts | Scripts to help with various related tasks |
Directory | Description |
---|---|
pages | Source for pages |
styles | Source for custom styling |
ui | Source for ui components |
stories | Source for storybook previews |
_series | Source for series info pages |
utils | Source for utility files |
Directory | Description |
---|---|
brand | Holds brand assets |
favicon | Holds favicon assets |
assets | Holds general assets |
assets/graphics | Holds graphics assets |
assets/icons | Holds icon assets (mainly for home page) |
assets/images | Holds image assets |
assets/images/series | Holds thumbnails for series pages |
Name | Description |
---|---|
master | What is running on the server — DON'T TOUCH |
develop | Where changes/development occurs |
Instructions for development/getting a development enviornment setup.
- Make sure you have the correct Node.JS and Yarn versions installed.
- Run
yarn
in top folder to install packages frompackage.json
. - Start the development server by running
yarn dev
. - Open http://localhost:3000 (dev server) in your browser.
- Follow the above steps first
- Start storybook by running
yarn storybook
. - Open http://localhost:6006 (storybook server) in your browser.
To run the app in production, you will need to use docker and docker-compose to
run both the Plausible server as well as the Next JS server. Folders for the servers
should also be cloned into /var/www/
.
Run the following commands from the top folder (this one). Also, if another version is already running, make sure to stop that container first.
- Build docker image:
docker build . -t carberra/website:<build version>
- Run docker image:
docker run -p 127.0.0.1:3000:3000 --name carberra-website --rm -d carberra/website:<build version>
To automatically build and deploy the docker container, all you have to do
is create a new tag with the version number (such as 1.0.0
) and then in
the next 6-10m approx. it will have built the docker container, sent it
to the server, stopped the old container, and started the new one on the
server, automating the whole process of deploying a new version.
Run the following commands from the Plausible hosting folder (the one cloned below).
- Clone hosting repo:
git clone https://github.com/plausible/hosting plausible
- Fill in info in
plausible-conf.env
(admin creds, etc).- Generate secket key to put in
SECRET_KEY_BASE
by runningopenssl rand -base64 64
- Generate secket key to put in
- Run the commands below under the every time header
- Verify all users:
docker exec plausible_plausible_db_1 psql -U postgres -d plausible_db -c "UPDATE users SET email_verified = true;"
- Build and start required images:
docker-compose up -d
You will find a very simple backup site in the html directory. This is meant
to function as a backup in case for some reason the docker container isn't running or
accessable. To do so, just setup the nginx config to send to the index.html
in that
directory as the backup page and you will be good to go.
To add a new series, you just need to create a markdown file for the series with the information required as well as any other information you want to include and place the thumbnail in the correct location.
Create a new markdown file in the _series directory, with the name being
what the url will be. So if the file is named how-to-python.md
, the url will be how-to-python
.
Then, you need to enter the metadata at the top of the file, which is used to construct the page and card, following the template below.
---
title: 'TITLE'
tagline: >
TAGLINE
thumbnail: '/assets/images/series/THUMBNAIL.jpg'
launch_date: 'DATE (YYYY-MM-DD)'
last_updated: 'DATE (YYYY-MM-DD)'
status: 'STATUS (ACTIVE, DORMANT, OR DEAD)'
playlist_link: 'https://www.youtube.com/playlist?list=PLAYLIST_ID'
---
An example of what this metadata should look like is shown below.
---
title: 'How to Python'
tagline: >
Ever wanted to get into Python, or even programming as a whole, but didn't know where to start? This playlist might be just for you.
thumbnail: '/assets/images/series/how-to-python.jpg'
launch_date: '2020-11-30'
last_updated: '2022-06-10'
status: 'Active'
playlist_link: 'https://www.youtube.com/playlist?list=PLYeOw6sTSy6bHRFwzIA3VAy05J2tJAAoS'
---
This information is used to create the series card as well as the top part of the series info page.
After that, you can add any extra information that you want (such as requirements, notes, etc.) on the page below the metadata area in markdown. This extra information will be rendered below the info section on the series info page.
Upload the thumbnail in jpg format to the folder for thumbnails, found at
assets/images/series/, ideally naming it the same name as
the corresponding markdown file. So if the markdown file was how-to-python.md
, then the
thumbnail file should be how-to-python.jpg
. Then link to that file in the thumbnail
metadata area in the markdown file and you are good to go.
---
title: 'How to Python'
tagline: >
Ever wanted to get into Python, or even programming as a whole, but didn't know where to start? This playlist might be just for you.
thumbnail: '/assets/images/series/how-to-python.jpg'
launch_date: '2020-11-30'
last_updated: '2022-06-10'
status: 'Active'
playlist_link: 'https://www.youtube.com/playlist?list=PLYeOw6sTSy6bHRFwzIA3VAy05J2tJAAoS'
---
## Required
- Python 3.10.2 or higher
## Optional
- WSL
## Notes
This is a beginner series. If you are not a beginner, most of this will probably cover items you already know. I would suggest skipping ahead to later intermediate or hard episodes of the series if you would like to watch.
- Favicon files generated using realfavicongenerator.net
If there are any questions, please get in contact with Parafoxia or MrDogeBro for help.