Edit

You will find below a basic documentation on how to achieve some common tasks in gae-init.

Before you even begin you have to make sure that you have all the requirements installed to their latest versions.

Once this is done, clone the project and run it locally:

$ git clone https://github.com/gae-init/gae-init.git foo
$ cd foo
$ npm install
$ gulp

Visit http://localhost:8080 to see the result. If you can see a normal functional page where you can sign in, that means everything went well and you are ready to start.

Execute the gulp command to start the local server and all the watchers. If everything went OK, visit http://localhost:8080.

All the custom styles are located under main/static/src/style/ directory and you can update them if needed. Most of the time though it is much better to create more files for better structure of the project. Here is how:

  1. Create a new file under main/static/src/style/ called foo.less.
  2. Open the style.less and append @import "foo"; at the end.

From now on, you can simply start adding new rules in the foo.less file and your web app will automatically refresh to reflect the changes.

Execute the gulp command to start the local server and all the watchers. If everything went OK, visit http://localhost:8080.

All the custom scripts are located under main/static/src/script/ directory and you can update them if needed. Most of the time though it is much better to create more files for better structure of the project.

Create new files (*.coffee or *.js) under main/static/src/script/ and your web app should automatically refresh to load the updated files.

The easiest way to add a frontend library is:

  1. Add it as a dependency in the bower.json, or try from console bower install --save dependency-name
  2. Update the overrides in bower.json, if necessary.
  3. Include the the styles in the styles.less.
  4. Include the scripts by updating the ext section in config.coffee. Note that if your front-end library has dependencies on other libraries being loaded, you will need to add them in here, too.
  5. Execute the gulp command if it's not already running (or restart it if it is).

By following these steps you will not need to add the third party libraries into your repository and everything will be minified before deployment.

If you are not able to include it as a bower dependency, simply create a new folder under the main/static/ directory and include them as descibed in the steps 3—5 above.

Check out the examples on how to include Bootswatch, Underscore or NProgress.

Since gae-init is running on Google App Engine, the Python library have to be compatible with App Engine.

The easiest way to add a new library is:

  1. Append the library into the requirements.txt.
  2. Execute gulp, if it's not already running.
  3. The newest library will have to appear under main/lib directory.
  4. Finally import it and use it in the project.

Check out the example on how to include Markdown.

Bunch of configuration variables are already being stored in our datastore and they are available globally accross the app. If you want to get the brand_name in Python you can access it with config.CONFIG_DB.brand_name and from HTML files via Jinja2 {{config.CONFIG_DB.brand_name}}.

If you want to add something new, start by adding a property in our Config model that is located in main/model/config.py:

foo = ndb.IntegerProperty(default=0)

..afterwards find the ConfigUpdateForm in the main/control/admin.py and something like:

foo = wtforms.IntegerField(model.Config.foo._verbose_name)

..finally add the following to template templates/admin/admin_config.html:

{{forms.number_field(form.foo)}}

By visiting the localhost:8080/admin/config/ you will be able to edit the new property.

Let’s Encrypt is a free, automated, and open certificate authority by the Internet Security Research Group (ISRG), that can provide SSL/TLS certificates. Here is how you can integrate it and use it with gae-init:

Use the Google Cloud Shell to execute the following docker commands:

docker run -it -p 443:443 -p 80:80 \
  -v "$(pwd)/ssl-keys:/etc/letsencrypt" \
  quay.io/letsencrypt/letsencrypt:latest \
  -a manual certonly

After following the instructions, filling the URL and email for the custom domain, you should get the challenge and the response back. Copy/paste them into the Admin > SSL section of the deployed app.

Before uploading the certificates to App Engine, convert the private key to a compatible format (replace www.example.com with your actual domain):

sudo openssl rsa -inform pem \
  -in ~/ssl-keys/live/www.example.com/privkey.pem \
  -outform pem > ~/ssl-keys/live/www.example.com/privkey_fixed.pem

Copy the contents of cert.pem & privkey_fixed.pem into the App Engine settings for SSL Certificats:

sudo cat ~/ssl-keys/live/www.example.com/cert.pem
sudo cat ~/ssl-keys/live/www.example.com/privkey_fixed.pem

Set up the custom domain and make sure that you have secure: always in your app.yaml.

For more details and screenshots follow the instructions by Igor Artamonov.

Make sure that you have created a new application on App Engine and the name of the application is updated in the app.yaml.

To deploy your application execute the following command from the root directory:

$ gulp deploy

If you wish to deploy it to a different application or a version then execute:

$ gulp deploy --project=foo --version=bar