Simple image hosting tool, with beautiful code written in TypeScript, serving a UI & RESTful API with user management.
Inspired by a tool of my friend Cludch
_{Made with ❤️ by derbl4ck and contributors}

❯ Why

My main goal with this project is to offer a tool that gives you the possibility to upload & serve screenshots on your own server instead of pushing it to providers like Imgur or ImageShack.

Try it!! Im happy to hear your feedback or any kind of new features.

Features

• Beautiful Code thanks to the awesome annotations of the libraries from pleerock.
• API Documentation thanks to swagger.
• API Monitoring thanks to express-status-monitor.
• Integrated Testing Tool thanks to Jest.

❯ Table of Contents

• Getting Started
• Scripts and Tasks
• Debugger in VSCode
• API Routes
• Project Structure
• Logging
• Docker
• Further Documentations
• Special thanks
• License

❯ Getting Started

Step 1: Set up the Development Environment

You need to set up your development environment before you can do anything.

Install Node.js and NPM

• on OSX use homebrew brew install node
• on Windows use chocolatey choco install nodejs

Install yarn globally

yarn install yarn -g

Install a MySQL database.

If you work with a mac, I recommend to use homebrew for the installation.

Step 2: Change Settings

Fork or download this project. Add your database connection information in the .env file.

Then setup your application environment.

yarn run setup

This installs all dependencies with yarn. After that it migrates the database and seeds some test data into it. So after that your development environment is ready to use.

Step 3: Serve your ImageHost2

Go to the project dir and start your ImageHost2 with this yarn script.

yarn start serve

This starts a local server using nodemon, which will watch for any file changes and will restart the sever according to these changes. The server address will be displayed to you as http://0.0.0.0:3000.

❯ Scripts and Tasks

All script are defined in the package-scripts.js file, but the most important ones are listed here.

Install

• Install all dependencies with yarn install

Linting

• Run code quality analysis using yarn start lint. This runs tslint.
• There is also a vscode task for this called lint.

Tests

• Run the unit tests using yarn start test (There is also a vscode task for this called test).
• Run the integration tests using yarn start test.integration.
• Run the e2e tests using yarn start test.e2e.

UI Tests only:

• Run ng test to execute the unit tests via Karma.
• Run ng e2e to execute the end-to-end tests via Protractor.

Running in dev mode

• Run yarn start serve to start nodemon with ts-node, to serve the app.
• The server address will be displayed to you as http://0.0.0.0:3000
• UI Development only: Run ng serve for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

Code scaffolding

• Run ng generate component component-name to generate a new component. You can also use ng generate directive|pipe|service|class|guard|interface|enum|module.

Building the project and run it

• Run yarn start build to generated all JavaScript files from the TypeScript sources (There is also a vscode task for this called build).
• To start the builded app located in dist use yarn start.

Database Migration

• Run typeorm migration:create -n <migration-file-name> to create a new migration file.
• Try typeorm -h to see more useful cli commands like generating migration out of your models.
• To migrate your database run yarn start db.migrate.
• To revert your latest migration run yarn start db.revert.
• Drops the complete database schema yarn start db.drop.

❯ Debugger in VSCode

To debug your code run yarn start build or hit cmd + b to build your app. Then, just set a breakpoint and hit F5 in your Visual Studio Code.

❯ API Routes

The route prefix is /api by default, but you can change this in the .env file. The swagger and the monitor route can be altered in the .env file.

Route	Description
/api	Shows us the name, description and the version of the package.json
/graphql	Route to the graphql editor or your query/mutations requests
/swagger	This is the Swagger UI with our API documentation
/monitor	Shows a small monitor page for the server
/api/users	Example entity endpoint
/api/images	Example entity endpoint

❯ Project Structure

Name	Description
.vscode/	VSCode tasks, launch configuration and some other settings
dist/	Compiled source files will be placed here
src/	Source files
src/api/controllers/	REST API Controllers
src/api/controllers/requests	Request classes with validation rules if the body is not equal with a model
src/api/controllers/responses	Response classes or interfaces to type json response bodies
src/api/errors/	Custom HttpErrors like 404 NotFound
src/api/interceptors/	Interceptors are used to change or replace the data returned to the client.
src/api/middlewares/	Express Middlewares like helmet security features
src/api/models/	Bookshelf Models
src/api/repositories/	Repository / DB layer
src/api/services/	Service layer
src/api/subscribers/	Event subscribers
src/api/validators/	Custom validators, which can be used in the request classes
src/api/resolvers/	GraphQL resolvers (query, mutation & field-resolver)
src/api/types/	GraphQL types ,input-types and scalar types
src/api/ schema.gql	Generated GraphQL schema
src/api/ swagger.json	Swagger documentation
src/auth/	Authentication checkers and services
src/core/	The core features like logger and env variables
src/database/factories	Factory the generate fake entities
src/database/migrations	Database migration scripts
src/database/seeds	Seeds to create some data in the database
src/decorators/	Custom decorators like @Logger & @EventDispatch
src/loaders/	Loader is a place where you can configure your app
src/public/	Static assets (fonts, css, js, img).
src/types/ *.d.ts	Custom type definitions and files that aren't on DefinitelyTyped
test	Tests
test/e2e/ *.test.ts	End-2-End tests (like e2e)
test/integration/ *.test.ts	Integration test with SQLite3
test/unit/ *.test.ts	Unit tests
.env.example	Environment configurations
.env.test	Test environment configurations
mydb.sql	SQLite database for integration tests. Ignored by git and only available after integration tests

❯ Logging

Our logger is winston. To log http request we use the express middleware morgan. There is a simple annotation to inject the logger in your service (see example below).

import { Logger, LoggerInterface } from '../../decorators/Logger';

@Service()
export class UserService {

    constructor(
        @Logger(__filename) private log: LoggerInterface
    ) { }

    ...

❯ Docker

Install Docker

Before you start, make sure you have a recent version of Docker installed

Build Docker image

docker build -t <your-image-name> .

Run Docker image in container and map port

The port which runs your application inside Docker container is either configured as PORT property in your .env configuration file or passed to Docker container via environment variable PORT. Default port is 3000.

Run image in detached mode

docker run -d -p <port-on-host>:<port-inside-docker-container> <your-image-name>

Run image in foreground mode

docker run -i -t -p <port-on-host>:<port-inside-docker-container> <your-image-name>

Stop Docker container

Detached mode

docker stop <container-id>

You can get a list of all running Docker container and its ids by following command

docker images

Foreground mode

Go to console and press + C at any time.

Docker environment variables

There are several options to configure your app inside a Docker container

project .env file

You can use .env file in project root folder which will be copied inside Docker image. If you want to change a property inside .env you have to rebuild your Docker image.

run options

You can also change app configuration by passing environment variables via docker run option -e or --env.

docker run --env DB_HOST=localhost -e DB_PORT=3306

environment file

Last but not least you can pass a config file to docker run.

docker run --env-file ./env.list

env.list example:

# this is a comment
DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306

❯ Further Documentations

Name & Link	Description
Express	Express is a minimal and flexible Node.js web application framework that provides a robust set of features for web and mobile applications.
Microframework	Microframework is a simple tool that allows you to execute your modules in a proper order, helping you to organize bootstrap code in your application.
TypeDI	Dependency Injection for TypeScript.
routing-controllers	Create structured, declarative and beautifully organized class-based controllers with heavy decorators usage in Express / Koa using TypeScript and Routing Controllers Framework.
TypeORM	TypeORM is highly influenced by other ORMs, such as Hibernate, Doctrine and Entity Framework.
class-validator	Validation made easy using TypeScript decorators.
class-transformer	Proper decorator-based transformation / serialization / deserialization of plain javascript objects to class constructors
event-dispatcher	Dispatching and listening for application events in Typescript
Helmet	Helmet helps you secure your Express apps by setting various HTTP headers. It’s not a silver bullet, but it can help!
Auth0 API Documentation	Authentification service
Jest	Delightful JavaScript Testing Library for unit and e2e tests
supertest	Super-agent driven library for testing node.js HTTP servers using a fluent API
nock	HTTP mocking and expectations library
swagger Documentation	API Tool to describe and document your api.
SQLite Documentation	Getting Started with SQLite3 – Basic Commands.
GraphQL Documentation	A query language for your API.
DataLoader Documentation	DataLoader is a generic utility to be used as part of your application's data fetching layer to provide a consistent API over various backends and reduce requests to those backends via batching and caching.

❯ Special thanks

Special thanks go to Project Express Typescript Boilerplate, which offers a great opportunity to start developing RESTful API Services in Node.js and to Project ArchitectUI, which is a great admin template based on Angular 7+, Bootstrap 4. Also thanks to Unsplash for the background image of the login.

❯ License

MIT