Skip to content

Remote linux server install

Jump to bottom
Vera Chellgren edited this page Mar 25, 2025 · 25 revisions

Set up Apache on your remote server

First, follow my tutorial for setting up a basic Apache server at https://github.com/verachell/Tutorial-Easy-customizable-Apache-server-setup-without-email and then come back here. The Apache setup tutorial will allow you to pick the level of security you want, so regardless whether you want a quick tryout of Zurfbirb or a long-term site, this tutorial has the info you need. It's also your choice whether or not to use a domain name.

Once you have done that, come back here.

At this point, you will have the control panel Webmin installed and you will have an Apache server that is capable of serving a static html file in your non-privileged user's directory.

You have a working apache server, but you need to add CGI ability to use Zurfbirb

Adding CGI programming ability

This consists of a few steps that we will do:

  • Activating appropriate Apache modules and updating Apache configuration
  • Testing using a perl script (reason: perl is already built in to the Ubuntu and Debian system)
  • Testing using a Ruby script

This allows us to check that we can do rudimentary CGI in ruby, before installing Zurfbirb. This ensures that any hiccups are ironed out along the way.

Enable the appropriate Apache modules needed for CGI

Log into webmin as root

go to Webmin menu -> Servers -> Apache

Click on the tab at top labeled Global Configuration. Then click on Configure Apache Modules. Then add cgi by clicking on it (not cgid) AND also rewrite

Then click Enable Selected Modules and then Save

FYI - the other existing apache modules (which came with your default install) should be:

access_compat, alias, auth_basic, authn_core, authn_file, authz_core, authz_host, authz_user, autoindex, deflate, dir, env, filter, mime, mpm_event, negotiation, reqtimeout, setenvif, status

Restart Apache - in terminal: systemctl restart apache2

Optional: If you are setting up a long term site you will want some protection against too many concurrent connections - this will help protect against DOS and DDOS attacks. For a short tryout, you won't need this. In the modules as above, check that you have mpm_event enabled. Then in Webmin menu -> Tools -> File Manager, open the file /etc/apache2/mods-enabled/mpm_event.conf. Change the values as follows:

StartServers            10
MinSpareThreads         10
MaxSpareThreads         10
ThreadLimit             10
ThreadsPerChild         10
MaxRequestWorkers       80
MaxConnectionsPerChild  0

Restart Apache - in terminal: systemctl restart apache2

Check global Apache directives

In Webmin menu -> Servers -> Apache, click on virtual server, then Edit Directives.

Check that your <Directory> section looks like this. If any line(s) are missing, add it in and save.

 Options +FollowSymLinks
 Require all granted
 AllowOverride All

If you made any changes in this section, then restart Apache - in terminal: systemctl restart apache2

Update local Apache directives

In Webmin, either as the root user or the non-privileged user, using Tools -> File Manager navigate to the folder containing index.html

Create a new file called .htaccess

put this text in the file:

# DISABLE DIRECTORY INDEXES
Options -Indexes +ExecCGI

# Add CGI handlers
AddHandler cgi-script .pl .rb
# Disable ETags
<IfModule mod_headers.c>
	Header unset ETag
</IfModule>
FileETag None

# Only allow get, post and head methods (not options, delete, etc etc)
<LimitExcept GET POST HEAD>
deny from all
</LimitExcept>

Tip: if after saving, you don’t see the .htaccess file in the directory, then (still in file manager) click on the settings gear icon at top right, then in Configuration Category drop down menu choose Advanced Options. Then set Show Hidden Files to Yes.

Testing CGI ability with perl script

Still in the same directory as index.html and .htaccess, create a new file called test.pl and put these contents in the file:

#!/usr/bin/perl
print "Content-type: text/html\n\n";
print "<!doctype html>";
print "<h1>Perl</h1>";
print "Hello, World.";

Note: in the line print "Content-type: text/html\n\n"; you do need the 2 newlines between the headers and the html content

Now, if you navigate the browser window to your.server.ip.address/test.pl you will likely get an error message such as Internal Server Error. This is because your perl file doesn't have execute permissions for the Apache user (in fact, it doesn't have execute perms at all). Tip: If you see the raw code displayed on the page instead, you have a problem with your .htaccess file - go back to the previous step, double check all spelling, check that .htaccess is located in the correct directory (the same one that index.html is in) - and restart Apache.

If, as is likely, you got the Internal Server Error message when looking at your site, ensure you are logged into Webmin as the non-privileged user and go to Webmin menu -> Tools -> Terminal

Navigate to your test.pl file e.g.

cd public_html

cd example (or whatever you called your site directory)

ls -alt

You will see there are no execute perms on test.pl , which we want to add for other. Type:

chmod o+x test.pl

Now reload the page in your browser window e.g. your.server.ip.address/test.pl It should just work and display the text. Congratulations! You now have CGI ability for perl. Next, we want to get CGI ability for ruby, which is critical before installing Zurfbirb.

Installing ruby

First we need to install ruby. Ideally, you want to install the full or development version of ruby because the regular version is not always going to be fully featured enough to be compatible with whatever gems will be used on the server.

You can use a ruby version manager if you know what you’re doing, which allows you to utilize different versions of ruby in different places on the server or control what version you’re using.

However, to save time in this tutorial we won’t use the version manager. We'll install the default full version of Ruby system-wide. In the command line in the Webmin terminal, assuming you're the non-privileged user, do these commands:

sudo apt update
sudo apt-get install ruby-full

remember, when it prompts you for password you need to give the new user password for Ubuntu or Debian (the one you created when you first created that new user), which is not necessarily the same one as you used when you logged into Webmin.

When the ruby install is done, to find out what version of ruby you now have, type

ruby -v

as long as it’s 3.0.0 or above (which it should be unless you have an outdated version of Ubuntu or Debian), the ruby will be compatible with Zurfbirb.

Testing CGI with ruby

This is the same idea as the perl test, but with ruby. Make a file called rubytest.rb inside your web root for that site (it will be in the same area as test.pl).

put these contents in rubytest.rb:

#!/usr/bin/ruby
puts "Content-type: text/html\n\n"
puts "<!doctype html>"
puts "<h1>Ruby</h1>"
puts "<p>Hello world</p>"

and then make it executable, similar to before, in the terminal in your webroot directory:

chmod o+x rubytest.rb

navigate your browser to your.server.ip.adress/rubytest.rb

You should see a page with a heading Ruby.

Tip: if you used a ruby version manager instead of installing system-wide, you should adjust the first line to reflect the location of your version of ruby - it may need to differ from #!/usr/bin/ruby

If you installed the default system-wide ruby as mentioned in this tutorial, then you don’t need to change that line.

Troubleshooting

It really should "just work" in ruby if the previous step in perl worked. Some things to check if it doesn’t work:

  • in the line puts "Content-type: text/html\n\n" you need the 2 newlines between the header and the html content
  • Make sure you have execute perms for other for your rubytest.rb file
  • If you’re not sure whether your first line of rubytest.rb contains the correct location for your Ruby e.g. #!/usr/bin/ruby then in the terminal do which ruby and the output will tell you where Ubuntu or Debian thinks Ruby is. If the output of which ruby differs from what you had in the first line, replace that first line path with the one from the which ruby output. Some of those are equivalent through being aliases, but it’s still worth checking this.
  • In case you accidentally didn’t restart Apache at a previous point, do it now (sudo if non-privileged user): sudo systemctl restart apache2

Assuming you can see the ruby html displayed in browser when navigating to your.server.ip.adress/rubytest.rb, move onto the next step

Installing Zurfbirb

Get the latest release of Zurfbirb from GitHub at https://github.com/verachell/Zurfbirb/releases, click on Source Code (zip) to download the file to your local machine anywhere (in the Downloads folder is fine, you can delete it later). It will be called something like Zurfbirb-x-y-z.zip . Do not unzip it, leave it there.

Now, in Webmin, make sure you are logged in as the non-privileged user. In the Webmin File Manager, navigate to the directory with the rubytest.rb and test.pl files. Click File -> Upload to Current Directory, then select from your local machine the zipped package you got. Once it is uploaded into Webmin, right-click on it and choose Extract. It will ask about overwriting existing files - choose yes.

Now it's time to install the gems and dependencies you need for Zurfbirb. For the quickest, easiest install on a remote server, we will do this using the sudo-gem script from zurfbirb - BUT this is only suitable if you are not using a ruby version manager. Here is how to know which category you are in:

  • Are you a beginner setting up a remote server according to this tutorial? If yes, then use the sudo-gem script (this will be described in a second)

  • Are you using a Ruby version manager? You should already know about it if you are! This is likely to apply if you are installing on your local machine and you are already using rvm or rbenv - we will describe further along what to do to install your gems. If unsure, then on whatever machine you are installing Zurfbirb on, type rvm -v and then rbenv -v. If you get command not found for both, then you do not have a ruby version manager and you can use Zurfbirb’s sudo-gem script.

For those using the sudo-gem script...

For those using the sudo-gem script go to Webmin terminal window, go to web root directory (where you installed Zurfbirb). Then go into the Zurfbirb folder as follows:

cd Zurfbirb-whatever (or whatever it is called - the directory, not the zip file)

Type

chmod u+x sudo-gems.sh

then type

./sudo-gems.sh

and the ruby gems and their other system dependencies you need will be installed. You may have to approve or answer yes to install questions (there may be several of these). Do not worry about if it says something is allowed to be uninstalled. On Debian, some of these steps can take awhile - the script could easily take 7 mins. It is faster on Ubuntu. It could take a long time doing “building native extensions” - it is not stuck, it just takes several minutes. Wait at least 10 mins for this!

Then skip ahead to "Running the Install Script"

For those using a ruby version manager...

If instead you are using a ruby version manager, you won’t want to install the gems as sudo which is how the helper script does it. Instead, you want to do (in terminal, as non-privileged user) and in your document root directory (the directory containing test.pl etc - NOT the zurfbirb directory inside that):

sudo apt-get install build-essential
sudo apt-get install pkgconf
sudo apt-get install sqlite3
gem install sanitize
gem install sqlite3
gem install sequel

What you are doing above is simply installing the 4 gems as the non-privileged user - the previous items are gem dependencies and those dependencies do need to be installed as sudo, which is why the code is written the way it is.

Running the install script

Now, regardless of whether you did the gems globally using the sudo-gems script or locally via version manager, it's time for the final step: running the install script.

Go to the Webmin terminal and navigate to the Zurfbirb directory if you are not already in it. Do ls -al. If the permissions on install.sh do NOT start with -rwx (i.e. if there is no x in user perms) do

chmod u+x install.sh

then do

./install.sh

And then Zurfbirb will install. Do not worry if it says device or resource busy - if you do ls -al afterwards and it shows nothing, it's ok. It unpacks into the directory level above, i.e. the document root you set up.

Then navigate in browser window to your server IP address, or if you used a domain name, the domain name. You should see the default home page for Zurfbirb. After this, we will move on to setting up an example page at https://github.com/verachell/Zurfbirb/wiki/Quickstart-tutorial-%E2%80%90-create-a-website-using-Zurfbirb First, we will remove unnecessary files. There is some troubleshooting info further below in case you are experiencing problems.

Before moving on

Once you have a home page, delete the following files that are no longer needed:

Delete rubytest.rb, index.html, test.pl and the .zip, .gz or tar.gz pkg, install.sh and sudo-gems.sh, OLD_htaccess, the (now empty) zurfbirb folder and, if you will not be using git for your project, remove .gitignore.

It can be surprisingly easy to accidentally delete files you did not mean to - be very careful not delete index.rb when you are deleting index.html! You can leave the files there if you wish, .htaccess protects them from being accessed (except for index.html) but it is better practice to remove them.

Pagination of File Manager is not perfect in Webmin - you may need to move between all the pages of your file list in the bottom right of file manager window to get to all the files, even if you think the file list should fit on 1 page

If everything is OK and you have the home page, move on to the tutorial for setting up an example site at https://github.com/verachell/Zurfbirb/wiki/Quickstart-tutorial-%E2%80%90-create-a-website-using-Zurfbirb

Troubleshooting

If you don't see the home page or you get an error message, do these things:

  • check that you have the new .htaccess file - it should now look different to the one you set up earlier. If it is the same as the old one, the install didn't work properly

  • check that the directory zurfbirb_for_apache exists in your user home directory (NOT the web root) - i.e. in /home/newuser AND that the zurfbirb_for_apache directory is either owned by the user www-data (or, failing that, that www-data has r,w,x perms). This directory should have been created by the install script.

  • on the browser, navigate to your.server.ip.address/404.html. If that goes ok then your basic setup is good but something is going on with your ruby situation. Double check previous steps, including installation of gems.

  • be sure all .rb files are executable by other, i.e. you want perms ending in x (index.rb, both files in the config folder, all rb files in the routed folder, and all rb files in core folder) - the install script should do this for you, but if it didn’t work, do it.

  • check error log at /var/log/apache2/error.log This will give you clues what is going on.

If none of this puts you on the right track, raise an issue on the repository

Clone this wiki locally