Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improved README for clarity, simplified installation and usage instructions #1886

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Improved README for clarity, simplified installation and usage instructions #1886

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 33 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,17 @@
[![first-timers-only-friendly](http://img.shields.io/badge/first--timers--only-friendly-blue.svg?style=flat-square)](https://code.publiclab.org#r=all)
[![View performance data on Skylight](https://badges.skylight.io/typical/ArYnJAb3VUC9.svg?token=DJ-zenCIFAootUAeQ8BkTiTkMBXkNpNc-PXTLA4dqDU)](https://www.skylight.io/app/applications/ArYnJAb3VUC9)

Use Public Lab's open source MapKnitter to upload your own aerial photographs (for example, those from balloon or kite mapping: https://publiclab.org/wiki/balloon-mapping) and combine them into:
MapKnitter is an open-source tool developed by [Public Lab](https://publiclab.org) that allows users to upload aerial photographs (from kites, balloons, drones, etc.) and stitch them together into maps. You can export these maps as:
- Web "slippy maps" (like Google Maps)
- GeoTiff
- TMS
- High-resolution JPEG

### Key Features
- Combine aerial imagery into cohesive maps
- Export in multiple formats (GeoTiff, TMS, JPEG)
- Client-side image distortion through the [Leaflet.DistortableImage](https://github.com/publiclab/Leaflet.DistortableImage) plugin

* Web "slippy maps" like Google Maps
* GeoTiff
* TMS
* High resolution JPEG

![demo](https://raw.githubusercontent.com/publiclab/mapknitter/master/public/demo.gif)

Expand Down Expand Up @@ -51,11 +56,10 @@ MapKnitter is broken into three major components:

## Installation

Please consider which installation method you prefer. Cloud Installation requires fewer steps and is platform agnostic, but you may value working from your terminal, for familiarity, more.

- [Cloud Installation](#cloud-installation)
- [Standard Installation](#standard-installation)
- [Windows Installation](#windows-installation)
Please choose the installation method that suits your environment:
- **Cloud Installation**: Fewer steps, works on any platform, recommended for quick setup.
- **Standard Installation**: Terminal-based installation for those familiar with working locally.
- **Windows Installation**: If you're using Windows, it's recommended to set up a virtual environment or dual-boot with Linux for smoother compatibility with Ruby on Rails.

<hr>

Expand Down Expand Up @@ -194,17 +198,20 @@ We recommend either working in a virtual environment or on a dual-booted system

<hr>

## Logging in when running locally
## Usage Guide

Because MapKnitter uses a remote, OpenID login system that depends on PublicLab.org, it can be hard to log in when running it locally. To get around this, we've created a local login route that requires no password:
### Logging in Locally
Since MapKnitter uses a remote OpenID login system, it may be challenging to log in locally without some tweaks. To work around this, we’ve created a local login route that doesn’t require a password.

You can log in locally at the path `http://localhost:3000/local/USERNAME` where `USERNAME` is the login name of a user saved on your database.
You can log in locally using:
http://localhost:3000/local/USERNAME

For this to work:
where `USERNAME` is the name of an existing user in your database.

- You will need to have copied and configured config/config.yml from config/config.yml.example.

- The user has to be an existing record. For your convenience, we have added two user accounts in [seeds.rb](./db/seeds.rb) to make their corresponding paths available in development after installation:
1. Configure the `config/config.yml` file as outlined in the installation steps.
2. After running the seeds file, two default user accounts will be available:
- `harry` for basic access: http://localhost:3000/local/harry
- `albus` for admin access: http://localhost:3000/local/albus

```Ruby
# basic account path - http://localhost:3000/local/harry
Expand Down Expand Up @@ -257,6 +264,15 @@ Help improve Public Lab software!
* Find lots of info on contributing at http://publiclab.org/wiki/developers
* Join our gitter chat at https://gitter.im/publiclab/publiclab

## Contributing

We encourage contributions to improve MapKnitter! If you're new to open source, check out the [First-Timers-Only issues](https://code.publiclab.org#r=all) to get started.

For general contributing guidelines, visit:
- [Contribution Guide](https://publiclab.org/wiki/contributing-to-public-lab-software)
- [Open Issues on GitHub](https://github.com/publiclab/mapknitter/issues)


## Staging infrastructure and testing

In addition to automatic testing with Travis CI, we have a branch (`unstable`) that is set to auto-build and deploy to [a staging instance](https://unstable.mapknitter.org/). This instance includes a copy of the production database and is intended for experimenting or debugging purposes in a production-like environment. We also have a `stable` build at https://stable.mapknitter.org/ which builds off of our `main` branch. Any commits or PRs merged to the main branch will trigger the `stable` server to rebuild, and you can monitor the progress at https://jenkins.laboratoriopublico.org/
Expand Down