Wiki.js on AWS User Guide

Overview

This image runs Wiki.js, the open source modern wiki and knowledge-base platform - a Markdown and visual editor, full-text search, page history and versioning, granular access control and many authentication options.

The Wiki.js Node server runs behind nginx as a reverse proxy. PostgreSQL is the datastore for pages, users and asset metadata; both bind to the loopback interface only. The server listens on 127.0.0.1:3000 and is reached through nginx on port 80 (and 443 once you add TLS).

The setup is completed and an administrator account is created on the first boot of every deployed instance; the login is written to /root/wiki-js-credentials.txt with mode 0600, and a fresh PostgreSQL password is generated per instance.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users will reach the wiki on
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Wiki.js. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users use. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes approximately one to two minutes after the instance state becomes Running (Wiki.js runs its database migrations and completes setup on first boot).

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Wiki.js Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=wikijs-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect and Retrieve the Administrator Login

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

The first boot service runs before the SSH daemon becomes ready, so the credentials file is always in place when you log in for the first time.

ssh <login-user>@<public-ip>
sudo cat /root/wiki-js-credentials.txt

You will see a plain text file containing the Wiki.js URL, the administrator email (admin@example.com) and the password. From the same SSH session you can confirm the deployment is healthy - the health endpoint is open:

curl -fsS -o /dev/null -w 'healthz HTTP %{http_code}\n' http://127.0.0.1/healthz

A healthz HTTP 200 response confirms the full stack - nginx, the Wiki.js server and PostgreSQL - is serving.

Step 4: First Sign-in

Open a web browser and navigate to http://<public-ip>/. Because first boot already completed the Wiki.js setup, browse to http://<public-ip>/login and enter the email and password from /root/wiki-js-credentials.txt.

The Wiki.js sign-in, served on first boot with a per-instance administrator login.

On a fresh instance there are no pages yet, so you are greeted with a welcome screen to create your first page or open the administration area.

The Wiki.js welcome screen.

Step 5: Create Your First Page

Select Create Home Page (or the + New Page button). Choose an editor - Markdown, the Visual Editor, or others - set the page path and title, write your content, and Save. Wiki.js renders the page and adds it to navigation and search. Page history and versioning are kept automatically.

Step 6: The Administration Area

Open the administration area from the user menu, or browse to http://<public-ip>/a. From here you manage the site, pages, users and groups, theme, navigation, search, authentication strategies and storage targets.

The Wiki.js administration dashboard.

Step 7: Add Users and Groups

In the administration area open Users to invite people (set their email, name and password, or connect an external authentication provider under Authentication). Use Groups to define what each set of users can read and write across page paths. Wiki.js supports local accounts plus many providers (LDAP, SAML, OAuth/OIDC, Google, GitHub and more).

Step 8: Enable HTTPS with Let's Encrypt

For any production deployment serve Wiki.js over HTTPS so logins and content cannot be intercepted. The image ships with nginx, which certbot can configure automatically.

The following assumes you have a DNS record pointing your fully qualified domain name at the instance's public IP address.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d wiki.your-domain.example \
  --non-interactive --agree-tos -m you@your-domain.example \
  --redirect

After certbot finishes, set the Site URL in the administration area under General to your HTTPS address so generated links are correct.

Step 9: Backups and Maintenance

Wiki.js keeps its content, users and settings in PostgreSQL, plus any locally-stored assets under /opt/wikijs. Back both up:

sudo -u postgres pg_dump wikijs > <backup-dir>/wikijs-db-$(date +%F).sql
sudo tar -czf <backup-dir>/wikijs-data-$(date +%F).tgz -C /opt/wikijs data

Ship both artifacts to an Amazon S3 bucket or another object store. Because the database is on its own EBS volume, you can also take coordinated EBS snapshots. Wiki.js can also store pages in Git, S3 and other targets configured under Storage in the administration area. For kernel and package updates, Ubuntu's unattended-upgrades is enabled by default. See https://docs.requarks.io/.

Step 10: Scaling Beyond a Single Instance

For larger deployments decouple Wiki.js from the single instance pattern:

• Move PostgreSQL to Amazon RDS for PostgreSQL and update the db section of /opt/wikijs/config.yml
• Configure a Storage target (Amazon S3, Git) in the administration area so assets are not tied to one instance
• Put the web tier behind an Application Load Balancer and serve assets through Amazon CloudFront

Each of these is documented in the official Wiki.js documentation at https://docs.requarks.io/.

Support

cloudimg provides 24/7/365 expert technical support for this image. Guaranteed response within 24 hours, one hour average for critical issues. Contact support@cloudimg.co.uk.

For general Wiki.js questions consult the documentation at https://docs.requarks.io/. Wiki.js is a trademark of its respective owner; use here is nominative and does not imply affiliation or endorsement.