For novices, what is the absolute simplest way of getting things set up?

34 views
Skip to first unread message

Thomas Wright

unread,
Mar 29, 2024, 7:14:31 AMMar 29
to FixMyStreet
Hi All,

I tried a few months ago to get a fixmystreet instance up and running for my local community. I ended up getting very bogged down trying to understand how to get things running with docker and mixing up the development and production environments, I left things stuck with a docker stack running in portainer that just crashes at load banging my head against a wall trying to get things running.
I run a little home automation server with plex and a few docker containers, and am used to tinkering with the likes of home assistant.
I'm coming back to try again with fixmystreet but I'd like a bit of help. Can you please treat me like a big dummy who has little experience running a linux server.

I have a separate beelink x86 machine I've bought just for fixmystreet. Ideally I'd like to be running this via docker so I have the option a few of my own containers down the line. I've got a domain ready and a DDNS pointing to my home IP, and will push that domain through a reverse proxy running on my other server.

With this setup can anyone help me out with what commands I should be running to get everything set up so that I can just get to tinkering with the high level yaml files and the branding files?
Assume I'm starting with a fresh install of ubuntu server and I've got my user accounts setup.

Thomas Wright

unread,
Apr 7, 2024, 10:01:56 AMApr 7
to FixMyStreet, Thomas Wright
Okay I managed to get an instance up and running, and now I'm trying to brute force my way to getting a working set of config files.
In any case, here are the steps I took to get a docker version of this up and running on my machine running ubuntu server

Install ubuntu server

As part of the install you optionally decide to create a separate storage volume, I created  ssa en ext4 format and with the mountpoint ssd for my fixmystreet install.

At the end make sure to include installing OpenSSH, I didn't install any of the optional extra features.

Logging into the server
After installing, you can switch over to using your normal machine and SSH into your server.
E.g. when on your server run the following command to print out your machine IP address 
hostname -I
Which should show your machine's IP address, something like 192.168.x.x

I use a windows machine normally, and use Powershell to SSH into my linux boxes
So I hit the windows button, and type "Powershell" and open that
In the PowerShell window type:
ssh user...@192.168.x.x

Where username is the user you set up as part of the ubuntu install and the IP address is the one you looked up. It should ask for your password and then let you in.

Install Git

Installed docker

Install docker-compose
(Step 1 already completed above)

Installed Portainer Community Edition (Optional)
Portainer makes it a lot easier for me to interact with the fixmystreet containers to restart them as necessary, although I couldn't get the actual installation to work from Portainer

Important - make sure to change the port portainer runs on from 8000 to something else as this clashes with the default port of FixMyStreet which is also 8000

Once installed you should be able to access Portainer on the port you specified, probably 9000
In your browser, go to 192.168.x.x:9000 (or whatever your server IP is) 
You should be prompted to set up a new account.
Once logged in, bookmark the page as Portainer.

Fork the fixmystreet repository
Even if you don't plan on making any changes, you'll probably end up tinkering with the cobrand templates or some other config files so it's worth forking the official repository so you can keep a backup on github of your work.
If you don't already have one, set up a github account https://github.com/signup

Click the Fork button in the top right and follow the prompts until you've completed the fork
Keep note of the URL of your forked repo for the next step.

Clone the repository to your server
Cloning will copy the repository to your local machine.
First create a folder for your installation.

Double check where you'll install by looking up your storage volumes and mountpoints with this command:
sudo lsblk -o NAME,FSTYPE,SIZE,MOUNTPOINT,LABEL

E.g. for me that pinted out:
NAME                      FSTYPE        SIZE MOUNTPOINT        LABEL
loop0                     squashfs     63.5M /snap/core20/2015
loop1                     squashfs    111.9M /snap/lxd/24322
loop2                     squashfs       87M /snap/lxd/27948
loop3                     squashfs     63.9M /snap/core20/2182
loop4                     squashfs     40.9M /snap/snapd/20290
loop5                     squashfs     39.1M /snap/snapd/21184
sda                       ext4        931.5G /ssd
nvme0n1                               238.5G
├─nvme0n1p1               vfat            1G /boot/efi
├─nvme0n1p2               ext4            2G /boot
└─nvme0n1p3               LVM2_member 235.4G
  └─ubuntu--vg-ubuntu--lv ext4          100G /

and I can see my largest mountpoint is /ssd - the volume I'd set up earlier for the install.

So I run the command
cd /ssd
Which opens that directory.

Then make a new directory for your install, something like "fixmystreet"
mkdir fixmystreet

Then open that directory
cd fixmystreet

Now you're in the right spot, you can clone your repository here, you'll need the URL of the repository you forked. E.g. in my case that is https://github.com/ThomasHFWright/fixmystreet
Then run the command to clone it using git:

Now you have the files, just initiate git to track any changes so you can pull them down as you make any on your local machine
git init

Now, when you make any changes to your repository you can pull the changes to your server using the command:
git pull

Start fixmystreet
Now you've cloned the repo, you can go ahead and build the stack of containers using docker-compose
In the same directory as you cloned into use the following command
docker-compose up
It should build the containers and start everything up with the default settings and passwords. Note that we expect to delete the containers created, this step is just to confirm things work.

After some time new messages will stop appearing, and you can hit ctrl z to stop viewing the docker-compose log.

Head to 192.168.x.x:8000 (or whatever your server IP is) and hopefully you should see the garish default view of fixmystreet running!

Clone the repository to your local machine
I run windows on my machine, so I installed git on it and use VS code to edit my repository
Install Git
With git you can clone your repository to your main computer, make changes and push them to github ready to pull them to your server.
I used the 64-bit Git for Windows Setup standalone installer.

Install VSCode
VSCode is a great program for editing code/config files and integrates well with Git to push changes to Github.

Clone your repository to your windows machine
Set up a new folder somewhere on your windows machine and then copy the path to that folder.
Open PowerShell.
type "cd " and then right click into powershell which will paste the folder path, should look like this:
cd path/to/new/folder
That will open the folder, and then you're ready to clone the repository again:

Load your repository in VSCode
Open up the folder you created in VSCode and things should work automatically, I think you'll get asked to install the source control and Github plugins, go ahead and do both.
You can use the Source control menu to push changes to Github, which will ask you to login to github when you do that the first time.


Removing credentials
Make note of the .gitignore file
This tells git not to push certain files to github - which is important for files which have things like your usernames and passwords in them. The docker-compose.yml and conf/general.yml files are both examples of files that by default have credentials in them you probably don't want to share.

I've used a docker-compose.override.yml file to move credentials I don't want shared on github to a .env file that contains my usernames and passwords.
Using an override file like this means I can leave the "docker-compose.yml" file alone and pull in any changes to that file from the main fixmystreet repository without any conflicts.
version: '3'

services:
  fixmystreet:
    environment:
      POSTGRES_PASSWORD: '${POSTGRES_PASSWORD}'
      SUPERUSER_EMAIL: '${SUPERUSER_EMAIL}'
      SUPERUSER_PASSWORD: '${SUPERUSER_PASSWORD}'
    volumes:
      - ${CORE_PATH}/conf/general.yml:/var/www/fixmystreet/fixmystreet/conf/general.yml
  postgres:
    environment:
      POSTGRES_PASSWORD: '${POSTGRES_PASSWORD}'

I've added several environment attributes stored in a separate .env file. These attributes are in the format ${ATTRIBUTE_NAME}
This is also where you can tell docker to read your files in your install folder, rather than the files in the docker image. This is the "volume" mapping above to the general.yml file. I've not mapped any other files yet, but I will have to in order to update to a new cobrand, otherwise the docker containers will have no idea I've added a new cobrand that's not in the standard docker package.

Then my ".env" file looks like this - the .env file is in the same base directory as docker-compose.yml
POSTGRES_PASSWORD='secretpasswordgoeshere'
SUPERUSER_EMAIL='mye...@mydomain.com'
SUPERUSER_PASSWORD='secretpasswordgoeshere'
CORE_PATH='/path/to/my/install/directory'

Since I have my secrets in the .env file, I added that to my .gitignore Installation section, and also commented out the line removing the docker-compose.override.yml. I also added the general.yml file since it contains my email credentials. Like so:
# Installation
/local
/local-*
.prove
.vagrant
.carton
META.yml
Makefile
blib/
inc/
_Inline/
*.pyc
#docker-compose.override.yml
.env
/conf/general.yml
Note that since these files are not tracked by git, they don't get pushed to Github, and so don't get pulled down to your server when you've made changes to them.
This means that changes to .env and /conf/general.yml have to be made directly on the server, or copied across manually.
I set up a Samba service on my server so that I could add my install directory as a network drive in windows and edit the files directly, but it's possible to edit the files in a SSH session with a text editor such as nano (nano needs installing with sudo apt install nano, don't use vim - it's impossible)

Updating config files and making changes

Make changes to your files in VSCode, and then when happy with those, push those to Github.
I'm not going to go into too much detail with git as I'm a novice myself.
It's usually sensible to create a new "branch" when working on a new feature and then "merge" that into the master branch once you're done working on it. Then you pull that "branch" down to your server and test it out.
If you mess up you can just discard the branch and reload from the master branch if all else fails.

You can create a new branch in VSCode by clicking on the "master" text in the Source Control menu on the left side of VSCode, then click "Create new branch" and give your branch a name.
Then you push that branch to github in the VSCode UI.

On your server, git pull to load the new branch
git pull
Then git switch to switch to that branch
git switch branch-name-goes-here

In future, to load updates use git pull.

Once you've loaded new changes, in Portainer go to your fixmystreet stack, select all four containers and then stop them. Wait for all four to stop, then start them again.
If the fixmystreet_fixmystreet_1 container refuses to start, you've probably made some formatting error in a yml file, but you can check the logs in Portainer.

Access fom the internet
I've not mentioned getting anything set up so that fixmystreet can be accessed from the internet.
For this I have the following setup:

Port forwarding
On my router I forward port 80 and 443 to my reverse proxy, I point both these ports to my reverse proxy IP and port.
In a simple case you could just forward both ports to port 8000 for fixmystreet.

DDNS
A DDNS service running in your network will tell your domain host to point your domain at your home IP address. Normally home IP addresses change pretty regularly, so this is required so that it keeps things up to date and correctly pointing to the right place.
I use Cloudflare as my domain host which adds some nice extra features.

My router has the option of setting up the DDNS service, though I run this on my Synology NAS instead.

Reverse Proxy (optional)
A reverse proxy is useful on your home network if you expose multiple services to the internet but don't want to open tons of ports on your router.
E.g. let's say you have a domain myhome.com and you want to allow access to both Portainer and your fixmystreet instance from the internet.
You could allow subdomains to be used and the reverse proxy points to the right place, such as portainer.myhome.com and fixmystreet.myhome.com will both point to your public IP (from your DDNS service) and your reverse proxy service runs within your network to point portainer.myhome.com internally to 192.168.x.x:9000 and fixmystreet.myhome.com to 192.168.x.x:8000.

I don't think many routers have the option of setting up a reverse proxy typically, I run mine on my Synology NAS.


Anyway, there's still lots more for me to run through so don't take this as a complete comprehensive guide, it's been my experience so far - and I haven't even started on the cobrand, getting email working correctly, or the mapping side of things!

I.TServiceNow

unread,
May 9, 2024, 1:00:42 PMMay 9
to FixMyStreet, thomas.h...@gmail.com

Hi Did yo have a chance to change any of the cobranding and customisation? I'm still trying to figure out how to customize my site.

Thomas Wright

unread,
May 10, 2024, 6:36:43 AMMay 10
to FixMyStreet, itservic...@gmail.com, Thomas Wright
Hey there,

Yeah it took me a bit of time to figure out the cobrand stuff, but I have it mostly working now.
Check out my fork on github to see the details. I'm using docker so this will be different if you've done a direct install.

I needed to set up docker to look at my custom cobrand files
has this line under the fixmystreet volumes:
./fixmybsresort-cobrand:/var/www/fixmystreet/cobrand

So that tells docker to look at the fixmybsresort-cobrand directory when fixmystreet is looking for the cobrand directory. You can name this whatever you want, even just "cobrand".
Then here is the contents of that directory for me:

In the structure there you'll see directorys called "fixmybsresort" - you need to rename these to whatever you called your cobrand in the ALLOWED_COBRANDS section of your   conf/general.yml-docker file (or conf/general.yml file if you overrode the file name in a docker-compose.override.yml file like I did)

After making any cobrand changes, I restart my fixmystreet docker container and that usually updates. Depending one what I've edited I sometimes need to delete the container fixmystreet container and run docker compose up again so that the css creation scripts run.

There is some documentation I found at one time about the minimum files you need to create for the cobrand to work, I can't find that right now but my example is pretty minimal. 
I think the absolute bare minimum is to create a base.scss which does a bunch of imports of other files, and also a  _colours.scss file to override the garish standard base colours:
With the import lines at the top:
@import "../sass/h5bp";
@import "./_colours";
@import "../sass/mixins";
@import "../sass/base";


That should get you going with a starting point to override other individual files like the site name and favicon.

Good luck with it!
Reply all
Reply to author
Forward
0 new messages