LibreScholar CMS

About LibreScholar

LibreScholar is a Content Management System that allows users to create a website, create and manage website pages, easily reference sources with IEEE citations, and manage uploaded files. Citations are stored in a database for reusability and are automatically formatted into IEEE citation format.

Requirements

• Download the LibreScholar repository to your computer using git
• SSH key on your computer for secure access to your server

Make sure to save and remember your SSH key's passphrase.

• A purchased Domain Name from a registrar like NameCheap.com
• DigitalOcean server and file storage costs in total $11/mo. This requires a DigitalOcean account, check the Setup section for details.

Installation

Add nameservers on Namecheap

• In Namecheap on the left click Domain List. On the right of your Domain name, click Manage. Under Nameservers click the dropdown and select Custom DNS
• Use Add Nameserver and add the three nameservers listed below. After adding the nameservers, click the green checkmark to save

ns1.digitalocean.com
ns2.digitalocean.com
ns3.digitalocean.com

Add your SSH Key to your DigitalOcean account

• In DigitalOcean on the left sidebar, under Account click Settings. Then click the Security tab and on the right click Add SSH Key. Add your Public SSH Key and a name label for your SSH Key.

Add Domain to DigitalOcean

• In DigitalOcean on the left sidebar, under Networking click Domains. On the right click Add a domain. Enter your Domain name and click Add domain.

Create Server

• In DigitalOcean on the left sidebar, under Compute click Droplets. On the right click Create Droplet.
  • Under Choose an image, Select Ubuntu 24.04 (default)
  • Under CPU Options, Select Regular
  • Under Select a Plan, Select $6.00/mo (minimum RAM requirement is 1 GB RAM)
  • Under Authentication and SSH Keys, Select the name label of your SSH Key
  • On the right, click Create Droplet

Add Domain records to DigitalOcean

• In DigitalOcean on the left sidebar, under Networking click Domains. You will create two records. On the right click Create a record.
  • Under Record Type, Select A
  • Under Hostname, Enter @
  • Under Will direct to, Select your Server
  • On the right, click Create Record
• Create another record the same way, but replace Hostname, with www

Create Spaces Object Storage Bucket for storing files

• In DigitalOcean on the left sidebar, under Storage click Spaces Object Storage. On the right click Create Bucket.
  • Under Content Delivery Network, Select the Enable CDN option.
  • Under Finalize, Enter a name label for your Spaces bucket.
  • On the right, click Create a Spaces Bucket.

Add Access Key for Spaces Bucket

• Click the Access Keys tab, then on the right click Create Access Key.
  • Under Select access scope, Select the Full Access option.
  • Under Give this access key a name, Enter a name label for your Access Key. Finally click Create Access Key.

Make sure to save and remember both the Access Key ID and Secret Key.

Configure CORS on your Spaces Bucket

• Click the Buckets tab, then click the name of your Spaces Bucket. Then click the Settings tab. To the right of CORS Configurations, click Add.
  • Under Origin, enter https:// followed by your domain name, e.g. https://librescholar.net
  • Under Allowed Methods, Select all five options.
  • Under Access Control Max Age, Enter 5.
  • Click Save CORS Configuration.

Configure .env

• On your computer in a terminal, navigate to LibreScholar root directory.
• In the root directory you will find the .env.example file. Create a copy of the .env.example file, and name it .env
• Open and edit .env
  • After APP_URL, enter your Droplet server's IPv4 address and save. ex. APP_URL=192.192.192.192

Server Provisioning

On your computer in a terminal, navigate to LibreScholar root directory. Enter the following command and press enter.

vendor/bin/dep provision

The provision command should only be run once per server

You may be asked to verify authenticity. This is to connect to your server using your SSH key. Verify the IP address is your server's IP address, then enter yes and press enter.

This command may take several minutes to complete.

Deployment

On your computer in a terminal, navigate to LibreScholar root directory. Enter the following command and press enter.

vendor/bin/dep installcms

The installcms command should only be run once per server

If asked for a password, press enter

Server Configuration

On your computer in a terminal, navigate to LibreScholar root directory. To login to your server, enter the following command and press enter.

vendor/bin/dep ssh

You should now be logged into your server in the ~/deployer/current directory. We will now edit the server's .env file. To open the file, enter the following command and press enter.

sudo nano .env

If prompted for a password, press enter

• After APP_URL, enter your domain name. ex. APP_URL=librescholar.net
• After DO_KEY, enter your Spaces Bucket's Access Key ID. ex. DO_KEY=DO123ABCEXAMPLE
• After DO_SECRET, enter your Spaces Bucket's Secret Key. ex. DO_SECRET=123ABCEXAMPLE
• After DO_BUCKET, enter your Spaces Bucket's name. ex. DO_BUCKET=my-spaces-bucket
• After DO_REGION, enter your Spaces Bucket's region. ex. DO_REGION=sfo3
• To save and exit, press ctrl+x
• When asked Save modified buffer?, press y
• When asked File Name to Write: .env, press enter

If you are having trouble finding your bucket's region, in DigitalOcean on the left navigate to Storage and click Spaces Object Storage. Your bucket's region can be found in the address of your bucket after the bucket's name. ex. sfo3 in https://my-spaces-bucket.sfo3.digitaloceanspaces.com

Create your Admin user

To create your admin user that you will use to author pages on your website, enter the following command and press enter.

php artisan create:admin "My Display Name" "myemail@example.com" "MyPassword"

Replace the three fields in quotes with your choice of display name, email, and password.

Your email can be any email. Your email will not be used as your LibreScholar website does not contain email functionality.

To login and use your website, use your email and password. Make sure to save and remember both.

CaddyServer Configuration

To navigate to the ~/deployer directory, enter the following command and press enter.

cd ~/deployer

To edit the Caddyfile config, enter the following command and press enter.

sudo nano Caddyfile

The first line will show your server's IP address, it should look something like

192.192.192.192 {

Replace the IP address with your domain name separated by a comma and space. For example:

librescholar.net, www.librescholar.net {

Add the ws subdomain to the end of the file. For example:

ws.librescholar.net {
  reverse_proxy 0.0.0.0:8080
}

Your Caddyfile config should look something like this.

librescholar.net, www.librescholar.net {
    ...
}

ws.librescholar.net {
  reverse_proxy 0.0.0.0:8080
}

• To save and exit, press ctrl+x
• When asked Save modified buffer?, press y
• When asked File Name to Write: Caddyfile, press enter

Enter the following command and press enter.

caddy reload

To disconnect from your server, enter the following command and press enter.

exit

Your website setup is now complete! To use your website, open a web browser and navigate to your domain name. Login with your admin account's email and password.

Creating Content Pages for your website

To create pages on your website, open up a browser and login with your admin email and password. On the left sidebar click Create Page.

• Enter a title for your page
• Enter Search Engine Optimization (SEO). This allows search engines to find your website.
• For page organization, you can add tags.

The text editor after tags is the default text Part. If you would like to add an image or pdf to your page, click the green button to the right.

If you would like to create a citation, in the text editor towards the right there are two buttons to create citations. After clicking the citation button, you can fill in your citation by pressing the buttons on the bottom bar. In the dropdown choose your source type. A source is for example the title of a book.

After you have finished editing your page, click the Save button on the bottom right.

Note: At this point your page cannot be seen on the internet

• If you want to show your page to the internet, click Publish
• If you want to hide your page from the internet, click Unpublish

Updating

If you would like to update your website to the newest version of LibreScholar, on your computer in a terminal, navigate to LibreScholar root directory. Enter the following command and press enter.

vendor/bin/dep updatecms

Exporting your website

If you want to create a copy of your website to a different domain name, you can easily do this by exporting your website as a csv. While logged in to your website, click the Export button.

Importing your website

To create a copy of your website using csv, follow the Installation instructions from the top

but instead of running

vendor/bin/dep installcms

run

vendor/bin/dep importcms

The importcms command should only be run once per server

If you will use a different Spaces bucket for file storage, then you will have to reupload the files in the Control Panel.

License

LibreScholar is open-sourced software licensed under the MIT license.