BookWyrm

https://docs.joinbookwyrm.com
Admin
BookWyrm is a social network for tracking your reading, talking about books, writing reviews, and...
Tokens:14,963
Snippets:290
Trust Score:9.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initialize Installation Directory

Source: https://docs.joinbookwyrm.com/install-prod-dockerless.html

Create and navigate to the target installation directory.

```bash
mkdir /opt/bookwyrm && cd /opt/bookwyrm
```

--------------------------------

### Setup Local Documentation Environment

Source: https://docs.joinbookwyrm.com/documentation.html

Commands to initialize a virtual environment and install dependencies for local documentation development.

```bash
python -m venv /path/to/new/virtual/environment
source <venv>/bin/activate
python -m pip install .

```

--------------------------------

### Setup Python Virtual Environment

Source: https://docs.joinbookwyrm.com/install-prod-dockerless.html

Commands to create the virtual environment and install dependencies.

```bash
python3 -m venv ./venv
```

```bash
./venv/bin/pip3 install --upgrade "pip>=25.1.0"
./venv/bin/pip3 install --group main
```

--------------------------------

### Setup System User and Services

Source: https://docs.joinbookwyrm.com/install-prod-dockerless.html

Commands to configure the system user and start background services.

```bash
useradd bookwyrm -r
```

```bash
chown -R bookwyrm:bookwyrm /opt/bookwyrm
```

```bash
sudo -u bookwyrm echo I am the $(whoami) user
```

```bash
cp contrib/systemd/*.service /etc/systemd/system/
```

```bash
systemctl enable bookwyrm bookwyrm-worker bookwyrm-scheduler
```

--------------------------------

### Initialize environment variables

Source: https://docs.joinbookwyrm.com/install-dev.html

Copy the example environment files to create the necessary configuration files for development.

```bash
cp .env.example .env
cp .env.dev.example .env.dev
```

--------------------------------

### Build and start development stack

Source: https://docs.joinbookwyrm.com/install-dev.html

Initialize secrets, build the Docker containers, and retrieve the initial admin code.

```bash
./bw-dev create_secrets # Create the secrets file with random values. You only need to do this once.
./bw-dev dev up --build # Build and start development stack
./bw-dev dev runweb python manage.py admin_code # Shows the admin-code for initial setup. You only need to do this once.
```

--------------------------------

### Admin Account Creation Code Example

Source: https://docs.joinbookwyrm.com/install-prod.html

Example output displayed when running the admin code command.

```text
*******************************************
Use this code to create your admin account:
c6c35779-af3a-4091-b330-c026610920d6
*******************************************
```

--------------------------------

### Initialize and Run BookWyrm Services

Source: https://docs.joinbookwyrm.com/install-prod.html

Commands for initializing secrets, database migrations, SSL, and starting the application containers.

```bash
./bw-dev create_secrets
```

```bash
./bw-dev init_ssl
```

```bash
./bw-dev migrate
```

```bash
docker-compose up --build
```

```bash
./bw-dev setup
```

```bash
./bw-dev admin_code
```

```bash
docker-compose up -d
```

--------------------------------

### Start Docker containers

Source: https://docs.joinbookwyrm.com/cli.html

Starts or restarts Docker containers with optional arguments.

```bash
docker compose up [args]
```

--------------------------------

### Install System Dependencies

Source: https://docs.joinbookwyrm.com/install-prod-dockerless.html

Install required packages on Debian-based systems to support the application.

```bash
apt install postgresql redis nginx python3-venv python3-pip python3-dev libpq-dev gunicorn gettext-base
```

--------------------------------

### Initialize PostgreSQL Database

Source: https://docs.joinbookwyrm.com/install-prod-dockerless.html

SQL commands to create the database user and schema.

```bash
sudo -i -u postgres psql
```

```sql
CREATE USER bookwyrm WITH PASSWORD 'securedbypassword123';

CREATE DATABASE bookwyrm TEMPLATE template0 ENCODING 'UNICODE';

ALTER DATABASE bookwyrm OWNER TO bookwyrm;

GRANT ALL PRIVILEGES ON DATABASE bookwyrm TO bookwyrm;

\q
```

--------------------------------

### Build development tools

Source: https://docs.joinbookwyrm.com/install-dev.html

Prepare the development container and tools for linting and formatting.

```bash
./bw-dev dev build # This is needed only once, if you haven't run dev stack previously
./bw-dev dev build dev-tools # This is needed only once and if you change pyproject.toml or Dockerfile
```

--------------------------------

### Clone the documentation repository

Source: https://docs.joinbookwyrm.com/documentation.html

Use this command to create a local copy of the documentation repository via the command line.

```bash
git clone https://github.com/bookwyrm-social/documentation.git
```

--------------------------------

### Run Django Management Commands

Source: https://docs.joinbookwyrm.com/install-prod-dockerless.html

Commands for database migration, initialization, and static file collection.

```bash
venv/bin/python3 manage.py migrate
```

```bash
venv/bin/python3 manage.py initdb
```

```bash
venv/bin/python3 manage.py compile_themes
```

```bash
venv/bin/python3 manage.py collectstatic --no-input
```

--------------------------------

### Run code quality tools

Source: https://docs.joinbookwyrm.com/install-dev.html

Execute formatters, type checking, and tests.

```bash
./bw-dev formatters
./bw-dev mypy
./bw-dev pytest
```

--------------------------------

### Configure Nginx

Source: https://docs.joinbookwyrm.com/install-prod-dockerless.html

Commands to copy and populate Nginx configuration templates using environment variables.

```bash
cp nginx/locations /etc/nginx/conf.d/locations
```

```bash
export DOMAIN=your-web-domain MAX_UPLOAD_MiB=100
```

```bash
envsubst '$DOMAIN,$MAX_UPLOAD_MiB' < nginx/server_config > /etc/nginx/conf.d/server_config
```

```bash
envsubst '$DOMAIN,$MAX_UPLOAD_MiB' < nginx/server_name > /etc/nginx/conf.d/server_name
```

```bash
envsubst '$DOMAIN,$MAX_UPLOAD_MiB' < nginx/https.conf > /etc/nginx/sites-available/bookwyrm.conf
```

```bash
envsubst '$DOMAIN,$MAX_UPLOAD_MiB' < nginx/reverse_proxy.conf > /etc/nginx/sites-available/bookwyrm.conf
```

```bash
ln -s /etc/nginx/sites-available/bookwyrm.conf /etc/nginx/sites-enabled/bookwyrm.conf
```

```bash
systemctl reload nginx
```

--------------------------------

### Migrate Local Media to S3

Source: https://docs.joinbookwyrm.com/external-storage.html

Execute this command to move existing local media files to the configured external S3 bucket.

```bash
./bw-dev copy_media_to_s3
```

--------------------------------

### Compile and Collect Static Assets

Source: https://docs.joinbookwyrm.com/external-storage.html

Commands to prepare themes and move static assets to the S3 bucket.

```bash
./bw-dev compile_themes
./bw-dev collectstatic
```

--------------------------------

### Enable S3 Storage in .env

Source: https://docs.joinbookwyrm.com/external-storage.html

Update the .env file to enable S3 storage. Optionally enable S3 for user exports as well.

```text
USE_S3=true
```

```text
USE_S3=true
USE_S3_FOR_EXPORTS=true
```

--------------------------------

### Clone and Configure BookWyrm

Source: https://docs.joinbookwyrm.com/install-prod.html

Commands to retrieve the application code and switch to the production branch.

```bash
git clone git@github.com:bookwyrm-social/bookwyrm.git
```

```bash
git checkout production
```

```bash
cp .env.example .env
```

--------------------------------

### Update BookWyrm Instance

Source: https://docs.joinbookwyrm.com/updating.html

Execute the update script to pull new code, rebuild images, run migrations, and restart containers.

```bash
./bw-dev update
```

--------------------------------

### Clone Application Code

Source: https://docs.joinbookwyrm.com/install-prod-dockerless.html

Retrieve the production branch of the BookWyrm repository.

```bash
git clone https://github.com/bookwyrm-social/bookwyrm.git --branch production --single-branch ./
```

--------------------------------

### Rebuild BookWyrm Instance

Source: https://docs.joinbookwyrm.com/install-prod.html

Apply changes to the cron configuration by rebuilding the container services.

```bash
docker-compose up --build
```

--------------------------------

### Run web container with ports

Source: https://docs.joinbookwyrm.com/cli.html

Executes an arbitrary command in the web container with ports exposed, useful for debugging with pdb.

```bash
docker-compose run --rm --service-ports web
```

--------------------------------

### Configure Nginx Cache Directory

Source: https://docs.joinbookwyrm.com/install-prod-dockerless.html

Create the Nginx cache directory and set appropriate ownership for the web server user.

```bash
mkdir /var/cache/nginx
chown www-data:www-data /var/cache/nginx
```

--------------------------------

### Configure Nginx with SSL Redirect

Source: https://docs.joinbookwyrm.com/reverse-proxy.html

Sets up an HTTP to HTTPS redirect and a secure server block for proxying traffic to BookWyrm.

```nginx
server {
    server_name your.domain;

    listen [::]:80;
    listen 80;
    add_header Strict-Transport-Security "max-age=31536000;includeSubDomains" always;
    rewrite ^ https://$server_name$request_uri;
    location / { return 301 https://$host$request_uri; }
}

# SSL code
ssl_certificate /etc/letsencrypt/live/your.domain/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your.domain/privkey.pem;

server {
    listen [::]:443 ssl http2;
    listen 443 ssl http2;

    server_name your.domain;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    location / {
        proxy_pass http://localhost:8001;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }

    location /images/ {
        proxy_pass http://localhost:8001;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }

    location /static/ {
        proxy_pass http://localhost:8001;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }
}
```

--------------------------------

### Generate Admin Code

Source: https://docs.joinbookwyrm.com/install-prod-dockerless.html

Command to generate the initial admin registration code.

```bash
sudo -u bookwyrm venv/bin/python3 manage.py admin_code
```

```text
*******************************************
Use this code to create your admin account:
c6c35779-af3a-4091-b330-c026610920d6
*******************************************
```

--------------------------------

### Sync Media to S3

Source: https://docs.joinbookwyrm.com/external-storage.html

Upload remaining local files to external storage.

```bash
./bw-dev sync_media_to_s3
```

--------------------------------

### Run command in web container

Source: https://docs.joinbookwyrm.com/cli.html

Executes an arbitrary command inside the web container.

```bash
docker-compose run --rm web
```

--------------------------------

### Restart Instance and Verify CORS

Source: https://docs.joinbookwyrm.com/external-storage.html

Restart the instance to apply changes and verify CORS configuration using curl.

```bash
./bw-dev up -d
```

```bash
curl -X OPTIONS -H 'Origin: http://MY_DOMAIN_NAME' http://BUCKET_URL/static/images/logo-small.png -H "Access-Control-Request-Method: GET"
```

--------------------------------

### Manage database migrations

Source: https://docs.joinbookwyrm.com/install-dev.html

Create and apply database migrations after modifying Django models.

```bash
./bw-dev makemigrations
./bw-dev dev migrate
```

--------------------------------

### View BookWyrm process logs with journalctl

Source: https://docs.joinbookwyrm.com/install-prod-dockerless.html

Use these commands to view logs for specific BookWyrm systemd services.

```bash
# viewing logs of the web process
journalctl -u bookwyrm

# viewing logs of the worker process
journalctl -u bookwyrm-worker

# viewing logs of the scheduler process
journalctl -u bookwyrm-scheduler
```

--------------------------------

### Re-populate Activity Streams

Source: https://docs.joinbookwyrm.com/updating.html

Use these commands to re-populate user feeds stored in Redis.

```bash
./bw-dev populate_streams
# Or use docker-compose directly
docker-compose run --rm web python manage.py populate_streams
```

--------------------------------

### Build Docker containers

Source: https://docs.joinbookwyrm.com/cli.html

Builds or rebuilds services defined in the configuration.

```bash
docker-compose build
```

--------------------------------

### Copy Backups from Container

Source: https://docs.joinbookwyrm.com/install-prod.html

Transfer database backup files from the Docker volume to the host machine.

```bash
docker cp <container_name>:/backups <host machine path>
```

--------------------------------

### Commit changes via command line

Source: https://docs.joinbookwyrm.com/documentation.html

Use this command to save changes to files in the local repository.

```bash
git commit
```

--------------------------------

### List Docker Containers

Source: https://docs.joinbookwyrm.com/install-prod.html

Identify the full name of the database service container to perform file operations.

```bash
docker-compose ps
```

--------------------------------

### Update BookWyrm dependencies and services

Source: https://docs.joinbookwyrm.com/updating-dockerless.html

Commands to update the application code, Python dependencies, and system services.

```bash
git pull
```

```bash
./venv/bin/pip3 install --upgrade "pip>=25.1.0"
```

```bash
./venv/bin/pip3 install --group main
```

```bash
venv/bin/python3 manage.py compile_themes
```

```bash
venv/bin/python3 manage.py collectstatic --no-input
```

```bash
venv/bin/python3 manage.py migrate
```

```bash
sudo systemctl restart bookwyrm bookwyrm-worker bookwyrm-scheduler
```

--------------------------------

### Run Django migrations

Source: https://docs.joinbookwyrm.com/cli.html

Executes Django migrations within the Docker container.

```bash
./bw-dev makemigrations bookwyrm 0108
```

--------------------------------

### Linode Object Storage Configuration

Source: https://docs.joinbookwyrm.com/external-storage.html

Set the custom domain for Linode object storage in the .env file.

```text
AWS_S3_CUSTOM_DOMAIN=my-bookwyrm-bucket.cluster-id.linodeobjects.com
```

--------------------------------

### Configure Default ACL for Backblaze

Source: https://docs.joinbookwyrm.com/external-storage.html

Set the default ACL to empty in the .env file when using Backblaze (B2) storage.

```text
AWS_DEFAULT_ACL=""
```

--------------------------------

### Push changes to fork

Source: https://docs.joinbookwyrm.com/documentation.html

Use this command to upload local changes to your fork on GitHub after making edits.

```bash
push
```

--------------------------------

### Merge generate.py across version branches

Source: https://docs.joinbookwyrm.com/documentation.html

Use this command to update the version list in older documentation branches to include a newly released version.

```bash
git checkout v0.x.y generate.py
```

--------------------------------

### Fix incorrect ISBN10 entries

Source: https://docs.joinbookwyrm.com/management-commands.html

Cleans up erroneously created 11-digit ISBN10 entries in the local database.

```bash
./bw-dev runweb python manage.py fix_isbn10_entries
```

--------------------------------

### Mapping Model Fields to ActivityPub

Source: https://docs.joinbookwyrm.com/activitypub.html

Use the activitypub_field argument in model field definitions to map model attributes to specific JSON keys.

```python
followers_url = fields.CharField(max_length=255, activitypub_field="followers")
```

--------------------------------

### User Model Definition

Source: https://docs.joinbookwyrm.com/activitypub.html

The User model inherits from OrderedCollectionPageMixin to support ActivityPub functionality.

```python
class User(OrderedCollectionPageMixin, AbstractUser):
    """a user who wants to read books"""
```

--------------------------------

### Defining Activity Serializer

Source: https://docs.joinbookwyrm.com/activitypub.html

Assign the activitypub data class to the model's activity_serializer attribute.

```python
activity_serializer = activitypub.Person
```

--------------------------------

### Stop Docker containers

Source: https://docs.joinbookwyrm.com/cli.html

Stops and removes containers, networks, and images created by up.

```bash
docker compose down
```

--------------------------------

### Update static files

Source: https://docs.joinbookwyrm.com/install-dev.html

Collect static files after making changes to CSS or JavaScript.

```bash
./bw-dev dev collectstatic
```

--------------------------------

### Configure Nginx Reverse-Proxy Server Block

Source: https://docs.joinbookwyrm.com/reverse-proxy.html

Defines the server block for routing traffic to the BookWyrm application on port 8001.

```nginx
server {
    server_name your-domain.com www.your-domain.com;

    location / {
        proxy_pass http://localhost:8001;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }

    location /images/ {
        proxy_pass http://localhost:8001;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }

    location /static/ {
        proxy_pass http://localhost:8001;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }

    listen [::]:80 ssl;
    listen 80 ssl;
}
```

--------------------------------

### Clean Docker containers

Source: https://docs.joinbookwyrm.com/cli.html

Removes all stopped Docker containers.

```bash
docker-compose stop
docker-compose rm -f
```

--------------------------------

### Set CORS rules for S3

Source: https://docs.joinbookwyrm.com/cli.html

Uploads a JSON file containing CORS rules to an S3 bucket.

```bash
./bw-dev set_cors_to_s3 cors.json
```

--------------------------------

### Person Data Class Definition

Source: https://docs.joinbookwyrm.com/activitypub.html

The dataclass structure for the Person ActivityPub object.

```python
@dataclass(init=False)
class Person(ActivityObject):
    """actor activitypub json"""

    preferredUsername: str
    inbox: str
    publicKey: PublicKey
    followers: str = None
    following: str = None
    outbox: str = None
    endpoints: Dict = None
    name: str = None
    summary: str = None
    icon: Image = None
    bookwyrmUser: bool = False
    manuallyApprovesFollowers: str = False
    discoverable: str = False
    hideFollows: str = False
    movedTo: str = None
    alsoKnownAs: dict[str] = None
    type: str = "Person"
```

--------------------------------

### Merge locale directory from l10n_main

Source: https://docs.joinbookwyrm.com/documentation.html

Use this command to pull the latest translation files from the l10n_main branch into your current working branch.

```bash
git checkout l10n_main -- locale
```

--------------------------------

### Configure CORS for S3 Bucket

Source: https://docs.joinbookwyrm.com/external-storage.html

Define CORS rules in a JSON file and apply them to the S3 bucket.

```json
{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://MY_DOMAIN_NAME", "https://www.MY_DOMAIN_NAME"],
      "AllowedHeaders": ["*"],
      "AllowedMethods": ["GET", "HEAD", "POST", "PUT", "DELETE"],
      "MaxAgeSeconds": 3000,
      "ExposeHeaders": ["Etag"]
    }
  ]
}
```

```bash
./bw-dev set_cors_to_s3 cors.json
```

--------------------------------

### Remove remote user preview images

Source: https://docs.joinbookwyrm.com/optional_features.html

Command to bulk delete preview images generated for remote users prior to version 0.5.4.

```bash
./bw-dev remove_remote_user_preview_images
```

--------------------------------

### Define Markdown Frontmatter

Source: https://docs.joinbookwyrm.com/documentation.html

Include this YAML block at the top of markdown files to set page metadata.

```yaml
Title: Documentation
Date: 2025-04-09
Order: 4

```

--------------------------------

### Insert Horizontal Rule

Source: https://docs.joinbookwyrm.com/documentation.html

Use this HTML tag instead of triple dashes to avoid conflicts with the documentation parser.

```html
<hr/>

```

--------------------------------

### Merge duplicate editions

Source: https://docs.joinbookwyrm.com/management-commands.html

Combines two edition records into one, preserving data in the canonical edition and updating references from the other.

```bash
./bw-dev runweb python manage.py merge_editions --canonical=27 --other=38
```

--------------------------------

### Identify duplicate authors

Source: https://docs.joinbookwyrm.com/management-commands.html

Lists potential duplicate author records based on name, birth/death dates, and book counts.

```bash
./bw-dev runweb python manage.py show_duplicate_authors
```

--------------------------------

### Implement Django translation tags in templates

Source: https://docs.joinbookwyrm.com/translation.html

Use the trans tag for literal strings and blocktrans for strings containing variables. The trimmed attribute removes unnecessary whitespace from blocktrans tags.

```html
<p>{% trans "This list is currently empty" %}</p>

<p>
    {% blocktrans trimmed with username=item.user.display_name user_path=item.user.local_path %}
    Added by <a href="{{ user_path }}">{{ username }}</a>
    {% endblocktrans %}
</p>
```

--------------------------------

### Merge duplicate authors

Source: https://docs.joinbookwyrm.com/management-commands.html

Combines two author records, migrating book associations and metadata to the canonical author record.

```bash
./bw-dev runweb python manage.py merge_authors --canonical=7 --other=46
```

--------------------------------

### Erase Activity Streams

Source: https://docs.joinbookwyrm.com/updating.html

Delete all stream data if the database has become corrupted or requires a full reset.

```bash
docker-compose run --rm web python manage.py erase_streams
```

--------------------------------

### Scale Celery workers

Source: https://docs.joinbookwyrm.com/monitoring-queue.html

Increase the number of concurrent Celery workers to handle higher task throughput.

```bash
./bw-dev up --scale celery_worker=3
```
Tokens:
Raw