Fix deployment problems

MonikaBarget commented 2 days ago

deploy.yml

Reconsider which branch to set: "main" or "gh-pages"?

on:
  push:
    branches:
      - gh-pages

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'  # Use Node.js 20

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Deploy
        run: npm run deploy

MonikaBarget commented 1 day ago

Branch set-up

The branch has to be set to Github Pages, and it does not work well to deploy directly from Github Actions. Publishing manually is recommended. An NPM token is needed for authentication.

Creating an NPM authentication

To publish or install packages from a private npm registry (such as npmjs.org), you need to authenticate via an npm token:

Log in to your npm account at npmjs.com.
Navigate to your Access Tokens (replace with your actual username).
Create a new token with the required permissions (read-only for installation, publish for publishing).
Add the npm Token as a GitHub Secret. Go to your repository on GitHub. Navigate to Settings > Secrets and variables > Actions. Create a new secret with the name NPM_TOKEN and paste the npm token you generated.
Update your GitHub Actions Workflow to include the npm authentication setup. You have to add the following information to your yaml file:

name: Authenticate to npm
      run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc

Other important settings

Node.js has to be set to (at least) 20. Older versions are deprecated. This set-up is defined in the yaml file:

yaml
1.  - name: Set up Node.js
2.    uses: actions/setup-node@v3
3.    with:
4.      node-version: '20'

Ensure that the project structure is correct and that the index file exits in the docs folder:

/root
  ├── docs
  │   ├── .vitepress
  │   │   └── config.js
  │   └── index.md
  ├── node_modules
  ├── package.json
  ├── package-lock.json
  └── vite.config.js

Ensure the VitePress build command is correctly configured to output to the expected directory. Check this in the github/workflows/deploy.yml file.
Ensure that docs/.vitepress/config.js is set up with your site’s settings and navigation.
Ensure that the build, dev and deploy scripts are correctly defined in package.json.

Commit any changes to your repository and rerun the workflow.

MonikaBarget commented 1 day ago

Manual deployment via Codespace Terminal

Log in to NPM

If Github Actions does not automatically publish for you, you can manually deploy via the terminal in Codespace, but you need to have NPM authentication. Before you can run commands for deployment, you need to log in to NPM within the terminal:

npm adduser

This will prompt you to add your username and password.

If you do not yet have an access token for your project yet, you can create it with the following command: npm token create

Allow VS Code access to browser clipboard

One problem can be that your browser does not allow VS Code to read from the clipboard to copy and paste the token, so perform the following steps if necessary:

Open Firefox and type about:config in the address bar, then press Enter.
Firefox will show a warning message about changing advanced settings. Click on "Accept the Risk and Continue".
In the search bar that appears, type clipboard.autocopy.
Set the clipboard.autocopy setting to true if it is not already.
Alternatively, search for the following setting: dom.events.testing.asyncClipboard
Ensure this is also set to true if your environment relies on the async clipboard API.

Pay attention to correct versioning

npm does not allow publishing a package with the same version number as an existing published version. Update the version number in your package.json file before publishing. For example, change from "version": "1.0.0" to "version": "1.0.1" or a higher version number. If your project or other projects depend on this version, update any references to use the new package name. For example, in dependencies or devDependencies in other package.json files.

Use deploy.sh script to publish

Instead of automating deployment via Github Actions, you can use a deploy.sh script. This script can handle building your VitePress site and deploying it to GitHub Pages. The deploy.sh script for the Distant Reading repository looks like this:

#!/bin/bash

# Exit script on any error
set -e

# Define variables
REPO_URL="https://github.com/monikabarget/DistantReading.git"
BRANCH="gh-pages"
BUILD_DIR="docs/.vitepress/dist"

# Print the current state
echo "Starting deployment script..."

# Checkout the repository
echo "Cloning the repository..."
git clone $REPO_URL --branch $BRANCH --single-branch deploy_repo

cd deploy_repo

# Clean the current deployment
echo "Cleaning previous deployment files..."
rm -rf *

# Copy the new build files
echo "Copying new build files..."
cp -R ../$BUILD_DIR/* .

# Commit and push the new build
echo "Committing and pushing changes..."
git config user.name "github-actions"
git config user.email "github-actions@github.com"
git add -A
git commit -m "Deploy updated site"
git push origin $BRANCH

# Go back to the original directory
cd ..

# Clean up
rm -rf deploy_repo

echo "Deployment complete!"

Before running the script, you have to make it executable in the terminal:

chmod +x deploy.sh

Then you can run:

./deploy.sh

If you want to integrate this script with GitHub Actions, you can create a workflow file that runs this script. Here’s an example of how you might set up a GitHub Actions workflow (in your yaml file) to run your deploy.sh script:

name: Deploy VitePress to GitHub Pages

on:
  push:
    branches: main
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Build VitePress site
        run: npm run docs:build

      - name: Run deploy script
        run: |
          chmod +x deploy.sh
          ./deploy.sh
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Trouble-shooting advice

Make sure the GITHUB_TOKEN has the correct permissions to push to the repository.
Place deploy.sh in your repository's root directory or adjust the script path accordingly. You can create a scripts directory to organize your deployment and other utility scripts.
Ensure that the REPO_URL and BRANCH variables match your actual repository settings and the branch where you want to deploy.
If you place deploy.sh in a scripts directory, you need to adjust the path in your GitHub Actions workflow file accordingly:

name: Run deploy script run: | chmod +x scripts/deploy.sh

  scripts/deploy.sh
env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

You may get a fatal: destination path 'deploy_repo' already exists and is not an empty directory notification when running npm run deploy. This error occurs because the deploy_repo directory was already created. This can happen when the script is run multiple times without cleaning up the previous clone. Modify the deploy.sh script to remove the deploy_repo directory if it exists before cloning the repository. This ensures that the directory is clean each time the script runs:

#!/bin/bash

# Exit script on any error
set -e

# Define variables
REPO_URL="https://github.com/monikabarget/DistantReading.git"
BRANCH="gh-pages"
BUILD_DIR="docs/.vitepress/dist"
DEPLOY_DIR="deploy_repo"

# Print the current state
echo "Starting deployment script..."

# Check if the deploy directory exists and remove it if it does
if [ -d "$DEPLOY_DIR" ]; then
  echo "Removing existing deploy directory..."
  rm -rf "$DEPLOY_DIR"
fi

# Clone the repository
echo "Cloning the repository..."
git clone $REPO_URL --branch $BRANCH --single-branch $DEPLOY_DIR

cd $DEPLOY_DIR

# Clean the current deployment
echo "Cleaning previous deployment files..."
rm -rf *

# Copy the new build files
echo "Copying new build files..."
cp -R ../$BUILD_DIR/* .

# Commit and push the new build
echo "Committing and pushing changes..."
git config user.name "github-actions"
git config user.email "github-actions@github.com"
git add -A
git commit -m "Deploy updated site"
git push origin $BRANCH

# Go back to the original directory
cd ..

# Clean up
rm -rf $DEPLOY_DIR

echo "Deployment complete!"

Alternative deploy.sh script:

#!/bin/bash

# Exit script on any error
set -e

# Define variables
REPO_URL="https://github.com/monikabarget/DistantReading.git"
BRANCH="gh-pages"
BUILD_DIR="docs/.vitepress/dist"
DEPLOY_DIR="deploy_repo"

# Print the current state
echo "Starting deployment script..."

# Ensure deploy directory is clean
if [ -d "$DEPLOY_DIR" ]; then
  echo "Directory $DEPLOY_DIR exists. Removing..."
  rm -rf "$DEPLOY_DIR"
fi

# Clone the repository
echo "Cloning the repository..."
git clone $REPO_URL --branch $BRANCH --single-branch $DEPLOY_DIR

cd $DEPLOY_DIR

# Clean the current deployment
echo "Cleaning previous deployment files..."
rm -rf *

# Copy the new build files
echo "Copying new build files..."
cp -R ../$BUILD_DIR/* .

# Commit and push the new build
echo "Committing and pushing changes..."
git config user.name "github-actions"
git config user.email "github-actions@github.com"
git add -A
git commit -m "Deploy updated site"
git push origin $BRANCH

# Go back to the original directory
cd ..

echo "Deployment complete!"

MonikaBarget / distant-reading