After setting installing crystalball on the server, a comparatively easy task awaits: Setting up and using github. This is crucial to maintaining your map, sharing development tasks with others, and most of all, for developing the map locally before uploading changes to your public map.
1. Go to your github account, or set one up. Then create what’s called a “bare repository” using your PROJECT name. This is a repository with nothing in it, no ReadMe, no gitignore, nothing, just the name.
2. Log into the server and cd to your PROJECT folder. It’s already initialized as a git repository because you initially installed it with git clone. Now run this command:
git remote -v
You should get this output, telling you where the repo can pull from and push to:
origin https://github.com/crystalball-mapkit/crystalball (fetch)
origin https://github.com/crystalball-mapkit/crystalball (push)
However that doesn’t help you because you don’t have permissions for that. So the first thing to do is to change your remote origin for both pull and push:
git remote set-url origin https://github.com/USERNAME/REPOSITORY.git
git remote set-url --push origin https://github.com/USERNAME/REPOSITORY.git
After that, run git remote -v again to verify that you have set up the remote origin for your new repository.
3. Now you are going to make your first commit, and then push to your repo. First run this, where MESSAGE is a brief commit message such as “First commit after installation”:
git commit -a -m "MESSAGE"
That will commit everything you have done so far. You need to do that whenever you make changes directly on the server – but in the future you won’t, you’ll do them on your local copy. First things first though: we have to populate the git hub repo. So you simply run this command, with your github username and password at the ready:
git push
4. OK, good enough, now you have a repo on github. Go there and copy the URL from the green button that says “Code.” Create a new folder on your local machine. Cd to that folder and run git clone:
git clone https://github.com/YOUR_REPONAME/PROJECT.git
Your remote origins are configured automagically, but you can cd to your local PROJECT folder and run git remote -v again to verify if you want.
5. The good thing about having a local repo is that you can develop the map locally and check your changes before actually committing them to the map. Most people consider this essential if they are running a production version that a lot of people are looking at: you don’t want your map jumping around and changing color while users are trying to do something with it! To make possible you will have to install a bunch of packages locally with pnpm – which we now use in place of npm, it’s faster. In addition to pnpm you have to install node, but the two can be done at the same time, following these instructions. Once you have done that, cd to your client folder (because you have to be on the client folder) and then run this:
pnpm install
It’s going to install a ton of packages and then when it’s done – while you are still cd’ed to your client folder – run this:
pnpm run dev
After that runs it will give you a browser address and voilà, you are running the map locally.
6. The only thing is, if you want to develop locally you are going to have to move your app-conf.json file back into the program. Otherwise you will be altering the production map whenever you change anything! To do this you will have to open your local repo with an editor (Atom, VScode or whatever you normally use). Navigate to app/client/src/main.js. Once again, go to line 51 (or whatever it is now) where the URL for app-conf on S3 appears between single inverted commas. You are going to replace that URL with a local address, so that the whole line looks like this:
fetch(‘./static/app-conf.json’)
Save main.js. Then navigate to app/client/public/static and you will see the “house copy” of your app-conf.json. Open it in the editor and replace the contents with the app-conf.json that you upload to S3. Save that. After you save it, go look at your localhost version of the map and you will see that it reflects any change you make in your “house copy” of the app-conf.
If you prefer, you can obviously work this way all the time. It’s not quite as convenient but it is safer and it does allow you to try out your changes locally before messing u your online version of the map.
7. When you’ve made your changes you have to get them up to the server and then into the docker containers. First you’re going to run git commit – -m “MESSAGE” (or you commit using your editor, doesn’t matter. Then you have to get back on the server and cd to your PROJECT folder. You will run these commands:
git fetch origin
git merge origin/master
docker-compose up -d --force-recreate --build client
The last one will take you client container down and rebuild it. That might take two minutes. Only when that is done will the online map reflect the changes made on your house copy of app-conf.json (and any other files you may have dared to alter!).
8. FNALLY, you may at times need to pull new functionalities that have been added to the original crystalball repostitory. From your perspective this will be the “upstream” repo. You need to add it to git as such:
git remote add upstream https://github.com/crystalball-mapkit/crystalball.git
You can verify that it worked using the same command as above:
git remote -v
You can add this both on your local machine and on your server, and you can pull to either. I find it more reassuring to pull to the local copy. It’s done like this:
git checkout master (just to be sure you are on the master branch)
git fetch upstream
git merge upstream/master
You may have to resolve merge conflicts by opening the local repo in VScode or some other editor – in that case, you should look up a tutorial on how it’s done (on VScode you will mostly just accept the incoming changes, it’s easy).. After resolving the conflicts, if any, you can push from your local branch to git hub, then go on to your server and pull those changes into your master branch. The changes may have affected more than just the client, so to update your full program, run this:
docker-compose up -d --force-recreate --build
Voilá, when it’s done you should be back online with some new functionalities!