GROWI Team Wiki on AWS User Guide

Overview

This image runs GROWI, the open source team wiki and knowledge base. Pages are written in Markdown with live preview, edited collaboratively in real time, and organised into a hierarchical page tree with revision history, comments, tags and attachments.

The stack is three tiers on one instance. A browser reaches nginx on port 80, nginx proxies to the GROWI Node.js application on port 3000, and the application stores everything in a local MongoDB 8.0 instance on port 27017. MongoDB binds to the loopback interface only and runs with authorization enabled against a credential unique to your instance.

GROWI's installation is completed automatically on the first boot of every deployed instance, so there is no browser setup wizard left exposed for the first visitor to claim. An administrator account is created with a password unique to that instance, written to /root/growi-credentials.txt with mode 0600, alongside a freshly generated MongoDB password and password hashing seed. Self registration is locked closed, so the wiki is never world writable.

Two dedicated EBS volumes ship with the image and are mounted by filesystem UUID: the MongoDB datadir at /var/lib/growi holding pages, revisions and attachments, and the GROWI application at /opt/growi. Both are independently resizable and separate from the operating system disk.

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

Port 3000 needs no inbound rule. nginx reaches the application over the instance's own loopback interface, so leave port 3000 closed in your security group.

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 GROWI. 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 and the two attached data volumes at their default sizes or larger.

Select Launch instance. First boot initialisation takes approximately one to two minutes after the instance state becomes Running: GROWI generates the per instance secrets, runs its database migrations, creates the administrator account and starts serving.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg GROWI 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> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=growi-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: Connecting to Your Instance

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:

Confirm the three services that make up the appliance are running:

sudo systemctl is-active mongod.service growi.service nginx.service

All three report active:

active
active
active

Confirm the versions of the components that are installed:

node -v
mongod --version | head -1
nginx -v 2>&1
node -p "require('/opt/growi/apps/app/package.json').version"

v24.18.0
db version v8.0.26
nginx version: nginx/1.24.0 (Ubuntu)
7.5.6

Step 4: Retrieve the Administrator Login

Every instance generates its own administrator password on first boot. Read the credentials file, which is readable only by root:

sudo ls -l /root/growi-credentials.txt
sudo grep -E '^(GROWI_URL|GROWI_ADMIN_USER)=' /root/growi-credentials.txt

-rw------- 1 root root 612 Jul 21 08:06 /root/growi-credentials.txt
GROWI_URL=http://203.0.113.10/
GROWI_ADMIN_USER=admin

Print the administrator password when you are ready to sign in, with sudo grep '^GROWI_ADMIN_PASSWORD=' /root/growi-credentials.txt | cut -d= -f2-. Run it only when you are about to use the value, and avoid leaving it in your shell history or terminal scrollback.

The file also records the MongoDB password and the password hashing seed for this instance. Treat the whole file as a secret, and store the administrator password in your password manager. Changing the hashing seed after the fact invalidates every existing password, so leave it alone.

Step 5: Confirm the Wiki Is Serving

nginx publishes an unauthenticated health endpoint that returns 200 as soon as the appliance is ready. It is a static nginx response and is suitable as the health check for an Application Load Balancer target group.

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

healthz: HTTP 200
login:   HTTP 200

Confirm which ports are listening. nginx serves on port 80, the GROWI application answers on port 3000, and MongoDB is bound to the loopback address only:

ss -ltn | grep -E ':80 |:3000 |:27017 '

LISTEN 0      4096       127.0.0.1:27017      0.0.0.0:*
LISTEN 0      511          0.0.0.0:80         0.0.0.0:*
LISTEN 0      511                *:3000             *:*
LISTEN 0      511             [::]:80            [::]:*

Because the application listens on all interfaces on port 3000, keep port 3000 out of your security group. Browsers should always arrive through nginx on port 80 or 443.

Finally, prove the administrator login works end to end against GROWI's own authentication API. This reads the password out of the credentials file into a shell variable, so the password is never printed:

PW=$(sudo grep '^GROWI_ADMIN_PASSWORD=' /root/growi-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'login round trip: HTTP %{http_code}\n' \
  -X POST http://127.0.0.1/_api/v3/login \
  -H 'Content-Type: application/json' \
  -d "$(printf '{"loginForm":{"username":"admin","password":"%s"}}' "$PW")"

login round trip: HTTP 200

Step 6: Sign In

Browse to http://<instance-public-ip>/ in a browser. GROWI redirects unauthenticated visitors to the sign in page.

Enter the username admin and the password from step 4, then select Sign in. GROWI opens the top page of the wiki, with the page tree on the left, the rendered page in the centre and the table of contents on the right.

The image ships with GROWI's own welcome content and a Sandbox section, which together are a working tour of the Markdown syntax the editor supports. They are ordinary pages, so delete or rewrite them once your own content is in place.

Step 7: Create and Edit Pages

Select the pencil icon at the top of the left sidebar to create a page, or Edit at the top right to edit the page you are viewing. The editor is a split view: Markdown source on the left, live rendered preview on the right.

Pages are addressed by path, and the path defines the tree. Creating /engineering/runbooks/database-failover places that page under /engineering/runbooks, creating the intermediate levels if they do not exist, so the structure of your wiki is simply the structure of its page names. Select Update to save. Every save is a revision, and the history is reachable from the page menu at the top right.

Attachments are stored in MongoDB GridFS, on the same dedicated data volume as your page content, so a snapshot of that volume captures both together.

Step 8: Administration

Open http://<instance-public-ip>/admin as the administrator to reach the wiki management area, which covers app settings, security, user and group management, markdown behaviour, appearance, plugins and full text search.

The Wiki Management Homepage confirms the running versions and the environment the appliance was configured with.

Self registration is set to Closed on this image, which is deliberate and different from GROWI's upstream default of Open. An open wiki on a public address lets any visitor create an account, so the image locks it closed on first boot. Add colleagues from User Management, where you can also grant another account administrator access. If you genuinely want open registration, change it under Security Settings with full awareness of who can reach the instance.

Step 9: The Data Volumes

The database and the application each sit on their own EBS volume, separate from the operating system disk:

df -hT /var/lib/growi /opt/growi

Filesystem     Type  Size  Used Avail Use% Mounted on
/dev/nvme1n1   ext4   20G  204M   19G   2% /var/lib/growi
/dev/nvme2n1   ext4   30G  2.6G   26G  10% /opt/growi

Both are mounted from /etc/fstab by filesystem UUID with the nofail option, so the layout survives reboots and relaunches and the instance still boots if a volume is ever detached:

grep growi /etc/fstab

UUID=92d54306-51f1-46e7-ac2c-eac9377c0453 /var/lib/growi ext4 defaults,nofail 0 2
UUID=3b8f0584-2199-4d99-a694-14a191b8b63e /opt/growi ext4 defaults,nofail 0 2

To grow the wiki's storage, modify the /var/lib/growi volume in the EC2 console or with aws ec2 modify-volume, then extend the filesystem on the instance with sudo resize2fs /dev/nvme1n1. Both operations are online and need no downtime.

Step 10: Enable HTTPS

Serve the wiki over TLS before putting real content into it. Point a DNS name at the instance, then either terminate TLS at an Application Load Balancer in front of the instance, or issue a certificate on the instance itself with Let's Encrypt. For the second approach, open port 443 in your security group and run certbot against the nginx site the image installs at /etc/nginx/sites-available/cloudimg-growi:

sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d <your-domain> -m <your-email> --agree-tos --no-eff-email

After TLS is in place, update the site URL GROWI advertises in links and notifications. Set APP_SITE_URL to the HTTPS address in /opt/growi/apps/app/.env.local and restart the application:

sudo systemctl restart growi.service

Step 11: Add Full Text Search

The image is deliberately single node, so GROWI's optional Elasticsearch or OpenSearch backend is not installed. Page browsing, the page tree and the table of contents all work without it; a search across the full text of every page does not.

To add it, stand up an Amazon OpenSearch Service domain reachable from the instance, add ELASTICSEARCH_URI to /opt/growi/apps/app/.env.local pointing at that domain, restart growi.service, then build the index from Full Text Search Management in the administration area.

Step 12: Backup and Maintenance

Everything that matters lives in MongoDB on /var/lib/growi, so there are two sound backup strategies and you should pick one.

The simplest is an EBS snapshot schedule on the /var/lib/growi volume, managed with Amazon Data Lifecycle Manager. This captures pages, revisions and attachments together and restores as a volume.

The alternative is a logical dump with mongodump, using the per instance MongoDB credential from /root/growi-credentials.txt and writing to a directory you then copy to Amazon S3:

MPW=$(sudo grep '^MONGO_PASSWORD=' /root/growi-credentials.txt | cut -d= -f2-)
sudo mongodump --uri "mongodb://growi:$MPW@127.0.0.1:27017/growi?authSource=growi" --out <backup-dir>

Apply operating system updates on your normal schedule with sudo apt-get update && sudo apt-get -y dist-upgrade, and reboot when the kernel changes. The three services start in the right order automatically, so no manual intervention is needed after a reboot.

To review what the application is doing, read its journal:

sudo journalctl -u growi.service -n 20 --no-pager

Support

This image is supported by cloudimg. Email support@cloudimg.co.uk with your instance ID and AWS Region for help with deployment and sizing, MongoDB administration and backup, TLS termination, attaching OpenSearch for full text search, GROWI upgrades, or troubleshooting.

GROWI is a trademark of its respective owner. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.