Portulan

About

Portulan is a project that lets you generate a website to showcase all of your services. It was originally created for homelabs but you may use it any way you can think of. It's actually the source code for all the Oblic Parallels portals.

How to use it

Configuration

If you want to use this project for yourself, you'll first want to edit the configuration file located at src/data/content.json. The file should look like this, don't hesitate to take the provided template file to make yours.

{
  "website_title": "Website Title",
  "website_logo": "https://...",
  "page_name": "",
  "website_status_link": "https://...",
  "colors": {
    ...  // Optional
  },
  "cards": [
    {
      "title": "Card One",
      "icon": "https://...",
      "description": "First description",
      "link": "https://..."
    },
    {
      "title": "Card Two",
      "icon": "https://...",
      "description": "Second description",
      "link": "https://..."
    }
  ]
}

Note

You can also use a relative path for your icons like that

 "icon": "../assets/some-icon.svg",

Optimized image loading

I would recommend to use only SVGs in your image links if possible. If it's not possible and that you want to optimize the loading time, you should use the lazy image loading.

Warning

This feature is not implemented yet and you'll have to go manually inside the src/components/ folder to make modifications. In order to use the lazy image loading you'll need to allow your source domain inside astro.config.mjs like following

import { defineConfig } from 'astro/config';

export default defineConfig({
  image: {
    // Add your domain 
    domains: ['resources.example.com'], 
  },
});

Then for each component that uses a raster image (PNG, JPG...) use the following syntax

---
import { Image } from 'astro:assets';
const { title, icon, ... } = Astro.props;
---

<Image 
  src={icon} 
  alt={title} 
  width={160} 
  height={160}
  quality="high"
  format="webp"
  loading="eager"
/>

Note that in this case, it would be a good idea to store your images in the assets folder an to access them using their relative path to let astro generate what it needs to fully take advantage of this feature.

Automatic deployment

There is a CI/CD pipeline in .forgejo/workflows/deploy.yaml that lets you automatically build and deploy the website. It's actually configured to do so with Oblic Parallels but you can easily use it to do the same thing on your own server. As it takes time I don't really want to document it right now but if you're interested, feel free to contact me or to open an issue and I will probably do it.

Structure

Project

• src/* - Source code (components, pages, styles, images, etc.)
• public/* - Non-code, unprocessed assets (fonts, icons, etc.)
• package.json - Project manifest
• astro.config.mjs - Astro configuration file
• tsconfig.json - TypeScript configuration file

src/

• assets/
• components/
• layouts/
• pages/
• scripts/
• data/ - Contains the configs to generate the website, each as a JSON file (contains cards, site name, colors, etc.)
• styles - default CSS style sheets and custom themes

Build

This project is meant to be used with pnpm, but you can use whatever package manager you want (at your own risk).

Commands

Command	Action
pnpm install	Installs dependencies
pnpm dev	Starts local dev server at localhost:4321
pnpm build	Build your production site to ./dist/
pnpm preview	Preview your build locally, before deploying
pnpm astro ...	Run CLI commands like astro add, astro check
pnpm astro -- --help	Get help using the Astro CLI