mirror of
https://codeberg.org/angestoepselt/homepage.git
synced 2025-05-24 14:46:16 +00:00
83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
# Angestöpselt Homepages
|
||
|
||
This repository mainly contains the next version of Angestöpselt's homepage, intended to be hosted at <angestoepselt.de>.
|
||
It is built with the [Eleventy](https://www.11ty.dev/) static site generator, using SCSS for stylesheets.
|
||
It also hosts the site for [CoderDojo Würzburg](https://coderdojo-wue.de).
|
||
|
||
## Project structure
|
||
|
||
The project's directory tree is structured as follows.
|
||
Note that this repository contains code to build different sites with some shared elements.
|
||
|
||
- **assets/** – Shared static content. This will be copied into the `assets` directory when building any site.
|
||
- **cgi-bin/** – CGI scripts. These are shared between sites, but not every site makes use of all the scripts. Note that these should not be called directly by site visitors. Rather they are called by rewriting paths in the server configuration where appropriate.
|
||
- **includes/** – Directory for [Eleventy includes](https://www.11ty.dev/docs/config/#directory-for-includes). This contains layouts and template files.
|
||
- **nix/** – Auxiliary build files used by the [Nix](https://nixos.org/) package manager.
|
||
- **playground/** – This directory contains anything that shouldn't be included directly but might be relevant to the project.
|
||
- **sites/** – Each site gets a subdirectory here containing its content.
|
||
- **<name>**
|
||
- **\_static/** – Site-specific static content.
|
||
- **assets/** – Site-specific assets. This will be copied into the `assets` directory of the final output.
|
||
- **\_data/** – Directory for Eleventy [global data files](https://www.11ty.dev/docs/data-global/).
|
||
- **\_images/** – Place images that should be rendered by the build system in some way here.
|
||
- **httpd.conf** – Configuration file for [lighttpd](https://redmine.lighttpd.net/projects/lighttpd/wiki#Documentation), which will serve the final site.
|
||
- _Anything else_ is actual content for the site (usually in the form of markdown files).
|
||
- **styles/** – SCSS stylesheets. Anything directly in this directory that doesn't begin with an underscore will be available in the final build.
|
||
- **.eleventy.js** – Base Eleventy configuration. This is set up so that the correct paths for the selected site (according to the environment variable `SITE`) are selected automatically.
|
||
- **.eleventyignore** – Eleventy ignore file. Place paths in here that should be excluded in the final build.
|
||
|
||
## Local development environment
|
||
|
||
To build the site locally, make sure you have Node installed (currently tested
|
||
with version 14). In Linux run:
|
||
|
||
```shell
|
||
npm install
|
||
npm run build:styles
|
||
SITE=angestoepselt npm run dev:site
|
||
```
|
||
If you are using Windows, you need to use the following commands in PowerShell instead:
|
||
```shell
|
||
npm install
|
||
npm run build:styles
|
||
$Env:SITE='angestoepselt'
|
||
npm run dev:site
|
||
```
|
||
|
||
|
||
Go to <http://localhost:8080/>, which will update live when content changes
|
||
(the initial build may take some time to render out the different image sizes).
|
||
If you make style changes, make sure to recompile the CSS files with the second
|
||
of the above commands. Alternatively, run `npm run dev:styles` in an additional
|
||
terminal to watch for changes.
|
||
|
||
### Nix environment
|
||
|
||
This repository also contains a [Nix flake](https://nixos.wiki/wiki/Flakes)
|
||
which contains the full development environment. `nix develop` will open a
|
||
shell with all required tools – you don't need to run `npm install` anymore.
|
||
Run `nix build ".#devEnv" -o .dev` to get a running Node environment in the
|
||
_.dev_ folder (for example to configure an IDE).
|
||
|
||
When Node dependencies are updated (this will change `package.json`), make sure
|
||
to run `./nix/update.sh` to update the npm lockfile and the Nix environment.
|
||
|
||
The flake also contains a second package for building the production output:
|
||
|
||
```shell
|
||
nix build # Will create an output derivation in 'result'
|
||
```
|
||
|
||
## Deployment
|
||
|
||
Deploy the container from the image automatically by the CI server.
|
||
Ask @yrd for the URL.
|
||
|
||
The container will expose the site under port 80.
|
||
Further configuration is available via environment variables.
|
||
|
||
- `ZAMMAD_URL=https://ticket.z31.it` – URL of the Zammad server to use.
|
||
- `ZAMMAD_GROUP=` – Set this variable to override the group all Zammad tickets go in. If empty (the default), different forms will be sorted into different groups.
|
||
- `ZAMMAD_TOKEN` – This is the only mandatory option. Set it to a Zammad access token with the `ticket.agent` permission.
|
||
|
||
See https://codeberg.org/angestoepselt/homepage/issues/6#issuecomment-419104 for details.
|