Skip to content

Using a Local Web Server

Jump to bottom
Jeff Parsons edited this page Nov 19, 2023 · 5 revisions

PCjs is always ready to run at pcjs.org, thanks to GitHub, since we updated the project to use GitHub Pages.

However, if you want to run PCjs locally, on your own computer, it's still fairly easy. Here's a summary of the basic steps to install Jekyll -- the HTML page generator used by GitHub Pages -- locally and run your own PCjs web server:

  1. Clone this repository onto your computer
  2. Install Ruby (on OS X, it should already be installed)
  3. Install Bundler (on OS X, run sudo gem install bundler)
  4. In the root of this repository, run bundle install
  5. Run bundle exec jekyll serve to start the web server

Now open a web browser and go to http://localhost:4000/. You're done!

Some useful server options include:

bundle exec jekyll serve --host=0.0.0.0 --port #

The --host=0.0.0.0 option makes it possible to access the web server from other devices on your local network; for example, you may want to run PCjs on your iPhone, iPad, or other wireless device. And --port allows you to override the port number (e.g., --port 80 if you simply want to use http://localhost/).

Last but not least, run bundle update periodically to keep Jekyll up-to-date.

NOTE: The old PCjs repository also included a Node-based web server. That feature (along with that entire repository) is no longer maintained, but it was nice option for Node users, it still works with the older repository, and perhaps someday we'll revisit creating a similar Node-based web server for the current repository.

Accessing Disk Images Locally

In the root of your PCjs repo, create a /disks folder and clone the pcjs disk repositories that you want to access locally:

mkdir disks
cd disks
git clone https://github.com/jeffpar/pcjs-diskettes.git diskettes
git clone https://github.com/jeffpar/pcjs-gamedisks.git gamedisks
git clone https://github.com/jeffpar/pcjs-miscdisks.git miscdisks
git clone https://github.com/jeffpar/pcjs-pcsigdisks.git pcsigdisks
mkdir cdroms
cd cdroms
git clone https://github.com/jeffpar/pcjs-cds001.git cds001
git clone https://github.com/jeffpar/pcjs-cds002.git cds002
git clone https://github.com/jeffpar/pcjs-cds005.git cds005

Next, edit _developer.yml, changing localdisks to true AND removing /disks from the exclude section.

Then start the Jekyll web server with the addition of _developer.yml:

bundle exec jekyll serve --host 0.0.0.0 --port 4000 --config _config.yml,_developer.yml

All the pages at localhost:4000 should now look for disk images in the local directories listed above; eg:

/disks/diskettes
/disks/gamedisks
/disks/miscdisks
/disks/pcsigdisks
...

If you don't use _developer.yml or you don't enable localdisks, PCjs will continue to map those paths to their corresponding online repository; eg:

Generating CD-ROM disc images for PCjs

CD-ROM images must be split into 32Kb chunks and named xNNNNN, where NNNNN is the chunk index.

The macOS version of split doesn't support the -d option to generate filenames with numeric suffixes, so install the GNU version (gsplit) using brew:

brew install coreutils

Then use gsplit like so:

gsplit -d -a 5 -b 32768 MISC-CD046-The_Way_Things_Work-1994.iso

The chunks must be added to a repository, and then XML files updated; eg:

/configs/pcx86/hdc/cdrom/library-atapi.xml
/configs/pcx86/hdc/47mb/unformatted-at5.xml

library-atapi.xml currently contains:

<?xml version="1.0" encoding="UTF-8"?>
<hdc id="cdrom" type="ATAPI" drives='[{name:"CD",type:0,path:"/disks/cdroms/cds005/microsoft/reference/Bookshelf-Windows-1991/cdrom"}]'>
	<control type="list" binding="listDisks" style="display:none">
		<disk path="/disks/cdroms/cds001/microsoft/games/Pandoras-Box/cdrom">Pandora's Box (1999)</disk>
		<disk path="/disks/cdroms/cds002/microsoft/tools/MSPL10/cdrom">Programmer's Library 1.0 (1988)</disk>
		<disk path="/disks/cdroms/cds002/others/misc/DKMMTWTW/cdrom">The Way Things Work (1994)</disk>
		<disk path="/disks/cdroms/cds005/microsoft/reference/Bookshelf-Windows-1991/cdrom">Bookshelf for Windows (1991)</disk>
	</control>
</hdc>

PCjs will automatically map paths such as /disks/cdroms/cds001/ to the appropriate repository (eg, https://cds001.pcjs.org/).

Clone this wiki locally