Skip to content

Commit 80ea956

Browse files
riffpointerriffpointer
committed
Add instructions for installing prerequisites on Ubuntu
1 parent accb644 commit 80ea956

3 files changed

Lines changed: 177 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,10 @@ This site is based on the [Klisé](https://github.com/piharpi/jekyll-klise) Jeky
1010
## Development
1111
See [Local Setup, Build, Serve, and Deploy](docs/local-setup-build-serve-deploy.md) for the local workflow and deployment path.
1212

13+
Detailed OS-specific guides:
14+
- [Windows Development Setup](docs/windows-development-setup.md)
15+
- [Ubuntu / Debian Setup](docs/ubuntu-setup.md)
16+
17+
1318
## License
1419
Licensed under the [MIT License](LICENSE)

‎docs/local-setup-build-serve-deploy.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,3 +121,8 @@ If the workflow fails, fix the reported issue locally, rebuild, and push again.
121121
## Windows Notes
122122

123123
If you are setting up on Windows, the repository also has a dedicated guide in [Windows Development Setup](windows-development-setup.md) with OS-specific installation steps and troubleshooting.
124+
125+
## Ubuntu / Debian Notes
126+
127+
If you are setting up on Ubuntu or a Debian-based Linux distribution, the repository also has a dedicated guide in [Ubuntu/Debian Setup](ubuntu-setup.md) with OS-specific installation steps and troubleshooting.
128+

‎docs/ubuntu-setup.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Ubuntu / Debian Development Setup
2+
3+
This project is a Jekyll site. On Ubuntu, Debian, and their derivatives (like Linux Mint, Pop!_OS, and Elementary OS), setting up the environment involves installing Ruby, build tools for compiling native gem extensions (like `sassc`), Bundler, and configuring your environment to install packages without root permissions.
4+
5+
## Prerequisites
6+
7+
To run this project locally, you need:
8+
9+
- **Git**
10+
- **Ruby** (and its development headers)
11+
- **GCC / Make** (build tools)
12+
- **Bundler**
13+
- **Node.js & npm** (optional, for local linting/CI checks)
14+
15+
---
16+
17+
## Step-by-Step Installation
18+
19+
Follow these steps to set up the development environment on your Ubuntu or Debian system.
20+
21+
### 1. Update Package Lists
22+
23+
Make sure your package manager's cache is up to date:
24+
25+
```bash
26+
sudo apt update
27+
```
28+
29+
### 2. Install System Dependencies
30+
31+
Install Ruby, compilation tools, and other libraries required to build native gem extensions:
32+
33+
```bash
34+
sudo apt install -y git ruby-full build-essential zlib1g-dev libffi-dev libssl-dev nodejs npm
35+
```
36+
37+
*Note: `ruby-full` includes the Ruby interpreter, development headers (`ruby-dev`), and standard libraries required to compile C-extension gems.*
38+
39+
### 3. Configure Gem Installation Path (Recommended)
40+
41+
By default, running `gem install` requires `sudo` privileges because it tries to write to system directories. To avoid using `sudo` (which can lead to file ownership issues and security risks), configure RubyGems to install gems to your home directory:
42+
43+
1. Create a directory for your local gems:
44+
```bash
45+
mkdir -p ~/gems
46+
```
47+
48+
2. Add environment variables to your shell configuration file (e.g., `~/.bashrc`, `~/.zshrc`):
49+
```bash
50+
echo '# Custom Ruby Gem path' >> ~/.bashrc
51+
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
52+
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
53+
```
54+
55+
3. Reload your terminal settings:
56+
```bash
57+
source ~/.bashrc
58+
```
59+
60+
### 4. Install Bundler
61+
62+
Install Bundler to manage the project's dependencies:
63+
64+
```bash
65+
gem install bundler
66+
```
67+
68+
Verify that Bundler is installed and accessible:
69+
70+
```bash
71+
bundle --version
72+
```
73+
74+
### 5. Clone the Repository
75+
76+
Clone the project and enter the repository directory:
77+
78+
```bash
79+
git clone https://github.com/riffpointer/riffpointer.github.io.git
80+
cd riffpointer.github.io
81+
```
82+
83+
*Note: If you have already cloned the repository, navigate to the folder in your terminal.*
84+
85+
### 6. Install Jekyll and Gem Dependencies
86+
87+
Install the Ruby gems specified in the [Gemfile](../Gemfile):
88+
89+
```bash
90+
bundle install
91+
```
92+
93+
This will compile and install all required gems locally.
94+
95+
### 7. Run the Site Locally
96+
97+
Start the local Jekyll server:
98+
99+
```bash
100+
bundle exec jekyll serve
101+
```
102+
103+
Once the server starts, you can view the site by navigating to:
104+
105+
```text
106+
http://localhost:4000
107+
```
108+
109+
To include draft posts in your local build, run:
110+
111+
```bash
112+
bundle exec jekyll serve --drafts
113+
```
114+
115+
If port 4000 is already in use by another application, specify an alternative port:
116+
117+
```bash
118+
bundle exec jekyll serve --port 4001
119+
```
120+
121+
---
122+
123+
## Running CI Validation Checks Locally
124+
125+
Before pushing changes to GitHub, you can run the primary markdown linting checks locally to match what runs in the GitHub Actions CI pipeline:
126+
127+
```bash
128+
bundle exec jekyll build
129+
npx --yes markdownlint-cli2
130+
```
131+
132+
---
133+
134+
## Troubleshooting Common Issues
135+
136+
### Issue: Permission Denied during `gem install` or `bundle install`
137+
- **Cause**: Ruby is trying to install gems globally in `/var/lib/gems/` which requires root access.
138+
- **Solution**: Follow **Step 3** to set up a local `GEM_HOME` in your home directory, or run the command with `bundle install --path vendor/bundle` (though setting `GEM_HOME` is generally preferred for a cleaner global-user workflow).
139+
140+
### Issue: Missing `mkmf` or native extension building fails
141+
- **Cause**: The compiler headers for Ruby or development libraries are missing.
142+
- **Solution**: Ensure you have installed `ruby-full` (or `ruby-dev` explicitly) and `build-essential`. Run:
143+
```bash
144+
sudo apt install -y ruby-dev build-essential
145+
```
146+
147+
### Issue: `jekyll` command not found
148+
- **Cause**: The executable is not in your system `PATH`, or you tried to run `jekyll` directly instead of via Bundler.
149+
- **Solution**: Always run commands prefixed with `bundle exec` (e.g., `bundle exec jekyll serve`), and ensure your `PATH` includes `~/gems/bin` as described in **Step 3**.
150+
151+
---
152+
153+
## Project Structure & Workflow
154+
155+
- **Configuration**: System configuration is defined in [`_config.yml`](../_config.yml).
156+
- **Posts**: Markdown files for blog posts live in [`_posts/`](../_posts/).
157+
- **Layouts**: Page structures live in [`_layouts/`](../_layouts/).
158+
- **Includes**: Reusable HTML/Liquid components live in [`_includes/`](../_includes/).
159+
160+
### Standard Development Flow
161+
162+
1. Update your local branch: `git pull`
163+
2. Update dependencies (if changed): `bundle install`
164+
3. Launch local server: `bundle exec jekyll serve`
165+
4. Preview and test your changes in the browser.
166+
5. Check markdown formatting: `npx --yes markdownlint-cli2`
167+
6. Commit and push your changes.

0 commit comments

Comments
 (0)