diff --git a/README.md b/README.md index 7cd8913..d171a1f 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,44 @@ docker restart gitea Gitea caches templates in production mode, so you need to restart the container for `.tmpl` changes to take effect. CSS and images are loaded directly from disk. Restarting the container is safe, and you may need to hard refresh your browser. +## Preview changes locally + +Before pushing, you can run a throwaway Gitea on your computer with this repository mounted as its custom folder, the same way the server mounts it. +You need Docker Desktop. +First, set the `image:` line in `preview/compose.yml` to match the one in `/opt/gitea/docker-compose.yml`, so the preview runs the same Gitea version as the server. + +```bash +docker compose -f preview/compose.yml up -d +``` + +Open http://localhost:3000. +The first visit shows Gitea's install page. +Keep SQLite, set the site title to `scient.ing git`, create an administrator account under "Administrator Account Settings," and click Install. +The preview keeps its data in Docker volumes, so you only do this once. + +The preview starts empty, so give it something to show: + +- Push any local clone, and Gitea creates the repository: `git push http://localhost:3000//.git main`. +- Or use New Migration in the + menu to copy a repository from git.scient.ing with its issues, pull requests, and releases. Private repositories need an access token. + +After you edit a file: + +- CSS and images: reload the page. Keep the browser's developer tools open with "Disable cache" checked, so it doesn't serve an old copy. +- Templates: run `docker compose -f preview/compose.yml restart`, then reload. + +The auto theme follows your system's light or dark setting. +To check the other mode without changing it, open the developer tools, run "Show Rendering" from the command menu (Cmd+Shift+P), and set "Emulate CSS media feature prefers-color-scheme." + +Pages worth a look after a change: + +- signed out: the home page, the sign-in page, and Explore +- signed in: the dashboard, your profile, and Settings, including Appearance +- in a repository: the file list, a file, the commit list, one commit's diff, the issue list, one issue, and a pull request's Files Changed tab +- Site Administration, and a missing page such as http://localhost:3000/nothing-here + +To stop the preview, run `docker compose -f preview/compose.yml down`. +Add `-v` to delete its data and start over. + ## License This repo is released under the MIT License (`LICENSE`). Because the theme files start from Gitea's own CSS, the notice also carries the copyright of The Gitea Authors and The Gogs Authors. Unlike the studio's tools, this repo is not under the Prosperity Public License, and you may use its source under the MIT License. diff --git a/preview/compose.yml b/preview/compose.yml new file mode 100644 index 0000000..650e542 --- /dev/null +++ b/preview/compose.yml @@ -0,0 +1,28 @@ +# Local preview of the theme: a throwaway Gitea with this repository mounted as its +# custom folder, read-only, the same way the server mounts it. +# +# Start: docker compose -f preview/compose.yml up -d then open http://localhost:3000 +# Stop: docker compose -f preview/compose.yml down add -v to delete the preview's data +# +# See "Preview changes locally" in README.md. +services: + gitea: + # Match the image line in /opt/gitea/docker-compose.yml so the preview runs the server's version. + image: docker.gitea.com/gitea:latest-rootless + container_name: gitea-preview + ports: + - "3000:3000" + environment: + - GITEA__database__DB_TYPE=sqlite3 + - GITEA__server__ROOT_URL=http://localhost:3000/ + - GITEA__ui__DEFAULT_THEME=scienting-auto + # Pushing to a repository that doesn't exist yet creates it, so any local clone can become test content. + - GITEA__repository__ENABLE_PUSH_CREATE_USER=true + volumes: + - preview-data:/var/lib/gitea + - preview-config:/etc/gitea + - ..:/var/lib/gitea/custom:ro + +volumes: + preview-data: + preview-config: