Configuration (.env)
Before starting TuxForge Pages, you must create a configuration file.
The application uses environment variables to control all behavior.
An example configuration is provided in .env.example.
Step 1: Create the config file
Copy the example file:
cp .env.example .env
Step 2: Edit the config
Open the file:
nano .env
You must update the following values:
GITEA_URL=https://git.example.com
- Replace with the full URL of your Gitea or Forgejo instance
GITEA_TOKEN=your_access_token_here
- Create a personal access token in Gitea/Forgejo
- Make sure it has permission to read repositories
MAIN_DOMAIN=pages.example.com
- This is the base domain used for hosting pages
- Example result: username.pages.example.com
INSTANCE_NAME=Tuxforge Pages
- Display name shown on landing and error pages
GITEA_BRANCH_NAME=pages
- The branch that contains static site files
- If this branch does not exist, the default branch will be used
GITEA_VERIFY_SSL=true
- Set to false only if your Gitea instance uses invalid/self-signed SSL
LOGO_URL=https://example.com/logo.png
- Public URL to a logo image
FAVICON_URL=https://example.com/favicon.ico
- Public URL to a favicon
- Can be the same as LOGO_URL if needed
PAGES_ROOT=./pages
- Local directory where repositories will be cloned
- You can change this to an absolute path like: /opt/tuxforge-pages/repos
PAGES_PUBLISH_DIRS=.,site,public,dist,build
- List of folders (comma separated) where static files may exist
- The server will look for index.html in these folders
- Order matters (first match is used)
TEMPLATES_DIR=./templates
- Path to HTML templates (landing page and error page)
- Must point to the correct folder
WEB_PORT=8080
- Port where the Python server runs
- Must match your Nginx proxy_pass configuration
Step 3: Important notes
- All paths can be relative or absolute, but must exist
- Make sure PAGES_ROOT is writable by the user running the service
- Make sure WEB_PORT matches the port used in Nginx (proxy_pass)
- MAIN_DOMAIN must match your DNS and Nginx config exactly
Step 4: Test configuration
You can test if the config loads correctly by running:
python3 main.py
If something is missing, the app will exit with an error like:
Missing required environment variable: GITEA_URL