portfolio-website/README.md

# Portfolio Website

This repository hosts my personal website and project portfolio.

The site is built with [Hugo](https://gohugo.io/), and this repository now includes a minimal custom Hugo setup with:

- a homepage
- a projects section
- reusable layouts
- custom styling without an external theme

## Purpose

This website is meant to:

- present my portfolio projects
- highlight my skills, experience, and interests
- provide a central place to share information about my work
- serve as the public source for my personal website

## Tech Stack

- Framework: Hugo
- Output: Static website
- Language: Markdown for content, templates for layout

## Getting Started

### Prerequisites

Install Hugo before running the site locally.

- Hugo installation guide: [https://gohugo.io/installation/](https://gohugo.io/installation/)

To verify your installation:

```bash
hugo version
```

### Run Locally

Start the development server with:

```bash
hugo server -D
```

Then open:

```text
http://localhost:1313
```

The `-D` flag includes draft content during local development.

## Build for Production

Generate the static site with:

```bash
hugo
```

The generated files will be placed in the `public/` directory.

## Project Structure

This repository currently follows a structure similar to the following:

```text
.
├── archetypes/
├── assets/
├── content/
├── layouts/
├── static/
├── hugo.toml
└── README.md
```

Depending on the Hugo configuration style, the main config file may also be named `config.toml`, `hugo.yaml`, or `hugo.json` in other projects.

## Content Management

Portfolio content is generally managed through the `content/` directory. Typical updates include:

- adding new project pages
- editing homepage and about page content
- updating images and downloadable assets in `static/`
- adjusting layouts and partials in `layouts/`

The current starter content is in:

- `content/_index.md`
- `content/projects/_index.md`
- `content/projects/*.md`

The current templates are in:

- `layouts/index.html`
- `layouts/_default/list.html`
- `layouts/_default/single.html`
- `layouts/partials/`

The current styles are in:

- `assets/css/main.css`

To create a new content page:

```bash
hugo new content/projects/my-project.md
```

## Deployment

This project is intended to be deployed as a static website.

Typical deployment options include:

- GitHub Pages
- Netlify
- Vercel
- any static file hosting provider

Deployment generally consists of building the site with Hugo and publishing the contents of the `public/` directory.

### Automated Deployment With Gitea

If your repository is hosted on Gitea, a practical approach is to use Gitea Actions with a workflow that:

- runs on every push to `main`
- builds the Hugo site
- uploads the generated `public/` directory to your server over SSH

This repository includes a starter workflow in `.gitea/workflows/deploy.yml`.

This assumes Gitea Actions is enabled and that you have at least one runner available for the repository.

To use it, you need a Gitea runner and the following repository secrets:

- `DEPLOY_HOST`: hostname or IP of your server
- `DEPLOY_PORT`: SSH port, usually `22`
- `DEPLOY_USER`: SSH user used for deployment
- `DEPLOY_PATH`: target directory served by your web server
- `DEPLOY_SSH_KEY`: private SSH key for the deployment user
- `DEPLOY_KNOWN_HOSTS`: optional full `known_hosts` entry to avoid runtime `ssh-keyscan`

Important: `DEPLOY_PORT` is the SSH port used for deployment, not the Nginx or website port. If Nginx serves the site on `8090` but SSH still listens on `22`, then `DEPLOY_PORT` must be `22`.

Example target path:

```text
/var/www/portfolio
```

Typical server-side setup:

- create a dedicated deployment user
- add the matching public SSH key to `~/.ssh/authorized_keys`
- configure Nginx or Caddy to serve the deployment directory
- ensure the deployment user has write permission on the target directory

#### Nginx Example

An example Nginx server block is included in `deploy/nginx/portfolio.conf`.

Typical installation steps on the server:

1. copy the config to `/etc/nginx/sites-available/portfolio.conf`
2. update `server_name` with your real domain
3. keep the `root` aligned with `DEPLOY_PATH`, for example `/var/www/portfolio`
4. enable the site with a symlink into `/etc/nginx/sites-enabled/`
5. test the configuration with `nginx -t`
6. reload Nginx with `systemctl reload nginx`

Example commands:

```bash
sudo cp deploy/nginx/portfolio.conf /etc/nginx/sites-available/portfolio.conf
sudo ln -s /etc/nginx/sites-available/portfolio.conf /etc/nginx/sites-enabled/portfolio.conf
sudo nginx -t
sudo systemctl reload nginx
```

If your server already uses HTTPS, keep Nginx terminating TLS and serving the files from `/var/www/portfolio`. If you do not yet have HTTPS, a common next step is to issue a certificate with Let's Encrypt and Certbot.

The deployment flow is then:

1. push changes to `main`
2. Gitea Actions builds the site with `hugo --minify`
3. the workflow synchronizes `public/` to the server with `rsync`
4. Nginx serves the static files directly from the deployment directory

If you prefer, this can also be adapted to:

- deploy to a Docker container
- publish to object storage such as S3-compatible hosting
- trigger a remote script on your server after upload

## Notes

- keep content in Markdown for simple maintenance
- use Hugo templates and partials to keep layouts reusable
- review generated pages locally before publishing changes

## License

This repository contains the source code and content for my personal website. Reuse terms can be added here if needed.